Documentation
API reference, MCP tools, and integration guides.
Get an API Key
Every snippet below expects a nams_... key. Replace the placeholder with your own.
Sign in to open your workspace — a default key is created for you, and the in-console Quick Start fills it into every snippet automatically. Or generate one on the API Keys page. Keys expire after 90 days.
REST: Make your first call
API keys work as Bearer tokens directly — no exchange step needed.
List entities
curl https://memory.neo4jlabs.com/v1/entities \ -H "Authorization: Bearer nams_YOUR_API_KEY"
1. Create a conversation
curl -X POST https://memory.neo4jlabs.com/v1/conversations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nams_YOUR_API_KEY" \
-d '{"userId": "user-1"}'
# Response: {"id": "conv-abc-123", ...}2. Add a message
curl -X POST https://memory.neo4jlabs.com/v1/conversations/CONV_ID/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer nams_YOUR_API_KEY" \
-d '{"role": "user", "content": "John works at Acme Corp in Denver"}'3. Check extracted entities
curl https://memory.neo4jlabs.com/v1/entities \ -H "Authorization: Bearer nams_YOUR_API_KEY" # Returns entities extracted from your messages: # John (person), Acme Corp (organization), Denver (location)
MCP: Connect an agent
Pick your client below. Each tab has the exact config snippet plus a 3-step verify check. The agent gets access to all 12 memory tools.
Claude Desktop's config does not accept a remote URL directly. Use the mcp-remote stdio bridge for static API keys, or open Settings -> Connectors -> Add custom connector for OAuth.
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"nams-memory": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://memory.neo4jlabs.com/mcp",
"--header",
"Authorization:Bearer ${NAMS_API_KEY}"
],
"env": {
"NAMS_API_KEY": "nams_YOUR_API_KEY"
}
}
}
}Save, fully quit Claude Desktop (Cmd/Ctrl+Q), reopen it. The nams-memory server appears under the tools (hammer) icon. Ask: 'List the NAMS memory tools you have.'
Windows note: keep 'Authorization:Bearer' with no space -- mcp-remote arguments break on whitespace there.
Anthropic's CLI coding agent. Native streamable-HTTP MCP and OAuth discovery.
Run from any project directory:
claude mcp add --transport http --scope project nams \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer nams_YOUR_API_KEY"
Start a session with `claude`, run `/mcp`, confirm `nams` is connected. Omit --header to use OAuth instead -- the first /mcp call opens a browser for PKCE.
OpenAI's terminal coding agent. Recent versions support remote streamable-HTTP MCP servers natively via TOML.
Edit ~/.codex/config.toml and add a server table.
[mcp_servers.nams] url = "https://memory.neo4jlabs.com/mcp" bearer_token_env_var = "NAMS_API_KEY"
Set NAMS_API_KEY in your shell, start a new Codex session, run `/mcp` to confirm `nams` is loaded. Older Codex installs are stdio-only -- wrap with `npx -y mcp-remote` instead.
Google's terminal coding agent. Use httpUrl (not url -- url silently routes through SSE, which this server does not expose).
Edit ~/.gemini/settings.json (or run `gemini mcp add -s user nams ...`):
{
"mcpServers": {
"nams": {
"httpUrl": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer $NAMS_API_KEY"
},
"timeout": 5000
}
}
}Set NAMS_API_KEY in your shell, restart any active Gemini session, run `/mcp`. Omit `headers` to trigger OAuth discovery on the server's 401 response.
AI code editor. Native streamable HTTP and OAuth discovery.
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project root):
{
"mcpServers": {
"nams": {
"url": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer ${env:NAMS_API_KEY}"
}
}
}
}Set NAMS_API_KEY in your shell, reload Cursor (Cmd/Ctrl+Shift+P -> Developer: Reload Window). Open Settings -> MCP and confirm `nams` is connected. Drop `headers` to use OAuth.
Codeium's Cascade-powered editor. Uses serverUrl (not url) for remote MCP endpoints.
Edit ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"nams": {
"serverUrl": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer ${env:NAMS_API_KEY}"
}
}
}
}Set NAMS_API_KEY in your shell, reload Windsurf or hit Cascade -> MCP servers -> Refresh. Confirm `nams` is connected. Omit `headers` for OAuth.
Prefer OAuth 2.0?
MCP clients that support OAuth can authenticate interactively with PKCE — no static key to manage. Discovery endpoints:
# Protected Resource Metadata (RFC 9728) https://memory.neo4jlabs.com/mcp/.well-known/oauth-protected-resource # Authorization Server Metadata (RFC 8414) https://memory.neo4jlabs.com/mcp/.well-known/oauth-authorization-server # Dynamic Client Registration (RFC 7591) POST https://memory.neo4jlabs.com/mcp/oauth/register
Access tokens are short-lived (1 hour); clients refresh automatically.
Base URLs
| API | https://memory.neo4jlabs.com/v1 |
| Auth | https://memory.neo4jlabs.com/v1/auth |
| MCP | https://memory.neo4jlabs.com/mcp |
Paste your API key in any endpoint's "Try it" panel to run requests against your workspace.
Authentication
Auth service base URL: https://gaylord.development.neo4jsandbox.com Returns the public RSA key(s) used to verify NAMS JWTs. Used by other services for token validation.
Responses
JWKS format public key set
Auth service base URL: https://gaylord.development.neo4jsandbox.com List all API keys for a workspace. Raw key values are never returned — only metadata (ID, label, created/revoked timestamps).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
workspace_id | query | string | required | Workspace ID |
Responses
Returns keys array with id, label, createdAt, revokedAt
{
"keys": [
"..."
]
}Missing workspace_id
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Generate a new API key for a workspace. The raw key is returned ONLY once — store it securely. It is bcrypt-hashed before storage and cannot be retrieved again. Scopes default to all if omitted.
Request Body
{
"label": "string",
"scopes": [
"string"
],
"workspace_id": "string"
}Responses
Key ID, raw key (save this), and label
{
"id": "string",
"key": "string",
"label": "string"
}Missing required fields
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Revoke an API key by ID. The key is immediately invalidated — any active JWTs issued from it are blocklisted. This action is irreversible.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | API key ID |
Responses
Returns status: revoked
{
"status": "success"
}Internal error
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Returns the decrypted raw API key value for keys created with encrypted storage. Returns 410 if the key was revoked or predates encrypted storage.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | API key ID |
workspace_id | query | string | required | Workspace ID that owns the key |
Responses
Key ID and decrypted raw key
{
"id": "string",
"key": "string"
}Missing workspace_id
{
"error": "internal error"
}Key not found for this workspace
{
"error": "internal error"
}Key revoked or not revealable
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Validate an Auth0 Bearer token via JWKS and return per-workspace NAMS JWTs. Automatically provisions a default workspace for first-time users. Returns an array of {workspace_id, token} pairs — one per workspace the user belongs to.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Authorization | header | string | required | Auth0 Bearer token |
Responses
Returns workspaces array with workspace_id and token
{
"workspaces": [
"..."
]
}Invalid or missing token
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Auth0 exchange not configured
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Handles OAuth2 authorization code flow. Exchanges the provider code for user info and returns a NAMS JWT. Currently returns 501 — implementation pending.
Request Body
{
"code": "string",
"provider": "string"
}Responses
JWT token (when implemented)
Not implemented
{
"error": "internal error"
}Auth service base URL: https://gaylord.development.neo4jsandbox.com Exchange a refresh token for a new access token and rotated refresh token.
Request Body
{
"refresh_token": "string"
}Responses
New access and refresh tokens
{
"refresh_token": "string",
"token": "string"
}Invalid request
{
"error": "internal error"
}Invalid or expired refresh token
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Short-Term Memory (Conversations)
List all conversations for the workspace. Returns metadata only (no messages).
Responses
Returns conversations array
{
"conversations": [
"..."
]
}Internal error
{
"error": "internal error"
}Create a new conversation session. Returns the conversation ID used for all subsequent message, context, and search calls. Entity extraction runs asynchronously after messages are added.
Request Body
{
"metadata": {},
"userId": "string"
}Responses
Returns id, workspaceId, userId
{
"id": "string",
"userId": "string",
"workspaceId": "string"
}workspace_id required
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Delete a conversation and all its messages.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Responses
Returns status: deleted
{
"status": "success"
}Internal error
{
"error": "internal error"
}Get conversation metadata by ID.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Responses
Returns id, workspaceId, userId, createdAt, updatedAt
{
"createdAt": "string",
"id": "string",
"updatedAt": "string",
"userId": "string",
"workspaceId": "string"
}Not found
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Get the structured context for an agent to build its prompt from. Returns three tiers: (1) reflections — highest-level compressed insights, (2) observations — mid-level summaries, (3) recentMessages — raw recent messages. Call this before constructing an agent's system prompt.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Responses
Returns reflections, observations, recentMessages arrays
{
"observations": [
"..."
],
"recentMessages": [
"..."
],
"reflections": [
"..."
]
}Internal error
{
"error": "internal error"
}List messages in a conversation, newest first. Use the limit parameter to control page size (default 50, max 200).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
limit | query | integer | optional | Max messages to return (1-200, default 50) |
Responses
Returns messages array
{
"messages": [
"..."
]
}Internal error
{
"error": "internal error"
}Add a message to a conversation. Triggers asynchronous entity extraction via the memory worker. Role must be "user", "assistant", or "system".
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Request Body
{
"content": "string",
"role": "string"
}Responses
Returns id, conversationId, role, content
{
"content": "string",
"conversationId": "string",
"id": "string",
"role": "string"
}Invalid role or missing fields
{
"error": "internal error"
}Conversation not found
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Add multiple messages to a conversation in a single request. Each message triggers async entity extraction independently. Maximum 100 messages per request.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Request Body
{
"messages": [
"..."
]
}Responses
Returns messages array with IDs
{
"messages": [
"..."
]
}Validation error
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Search messages within a conversation by content. Uses vector similarity search when embeddings are available, falling back to text CONTAINS. Returns searchType field indicating which method was used.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Request Body
{
"limit": 0,
"query": "string"
}Responses
Returns messages array and searchType
{
"messages": [
"..."
],
"searchType": "vector"
}Missing query
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Long-Term Memory (Knowledge Graph)
List all entities in the knowledge graph. Filter by type using the optional query parameter.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
type | query | string | optional | Filter by type: person, organization, location, concept, tool, custom |
Responses
Returns entities array
{
"entities": [
"..."
]
}Internal error
{
"error": "internal error"
}Create a new entity in the knowledge graph. Entities are automatically created during entity extraction, but can also be created manually.
Request Body
{
"description": "string",
"name": "string",
"type": "string"
}Responses
Returns id, name, type, description
{
"description": "string",
"id": "string",
"name": "string",
"type": "string"
}Missing required fields
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Get the full entity graph with nodes and edges for visualization. Used by the Memory Browser in the dashboard.
Responses
Returns nodes and edges arrays
{
"edges": [
{}
],
"nodes": [
{}
]
}Internal error
{
"error": "internal error"
}Search entities by name or description. Uses vector similarity search when embeddings are available, falling back to text CONTAINS. Returns searchType field indicating which method was used.
Request Body
{
"limit": 0,
"query": "string",
"type": "string"
}Responses
Returns entities array and searchType
{
"entities": [
"..."
],
"searchType": "vector"
}Missing query
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Delete an entity and all its relationships from the knowledge graph.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Entity ID |
Responses
Returns status: deleted
{
"status": "success"
}Internal error
{
"error": "internal error"
}Get entity details including all relationships (incoming and outgoing edges in the knowledge graph).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Entity ID |
Responses
Returns entity fields and relationships array
{
"confidence": 0,
"createdAt": "string",
"description": "string",
"id": "string",
"name": "string",
"relationships": [
"..."
],
"sourceStage": "string",
"type": "string",
"updatedAt": "string"
}Not found
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Update an entity's name or description.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Entity ID |
Request Body
{
"description": "string",
"name": "string"
}Responses
Returns status: updated
{
"status": "success"
}Invalid request
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Provide feedback on entity quality. userScore is a float 0-1 representing confidence. confirmed=true marks the entity as human-verified.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Entity ID |
Request Body
{
"confirmed": false,
"userScore": 0
}Responses
Returns id, updated: true
{
"id": "string",
"updated": false
}Invalid request
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Get cross-conversation history — all messages that mention this entity, across all conversations in the workspace.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Entity ID |
Responses
Returns entityId and mentions array
{
"entityId": "string",
"mentions": [
{}
]
}Internal error
{
"error": "internal error"
}Merge the source entity into a target entity. All relationships are transferred to the target. A SAME_AS relationship is created for provenance. The source entity is not deleted but becomes inert.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Source entity ID |
Request Body
{
"targetId": "string"
}Responses
Returns status: merged, sourceId, targetId
{
"sourceId": "string",
"status": "merged",
"targetId": "string"
}Missing targetId
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Observational Memory
List compressed observations for a conversation. Observations are auto-generated summaries of message windows, created by the memory worker after sufficient messages accumulate.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
limit | query | integer | optional | Max observations to return (1-200, default 50) |
Responses
Returns observations array
{
"observations": [
"..."
]
}Internal error
{
"error": "internal error"
}List reflections for a conversation. Reflections are higher-level insights synthesized from multiple observations. Each new reflection supersedes the previous.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | required | Conversation ID |
Responses
Returns reflections array
{
"reflections": [
"..."
]
}Internal error
{
"error": "internal error"
}Reasoning Memory
Get a detailed explanation of a reasoning step including its tool calls and the entities it influenced.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
stepId | path | string | required | Step ID |
Responses
Returns step details, toolCalls, and influencedEntities
{
"actionTaken": "string",
"conversationId": "string",
"createdAt": "string",
"id": "string",
"influencedEntities": [
"..."
],
"reasoning": "string",
"result": "string",
"toolCalls": [
"..."
]
}Step not found
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Get the reasoning chain that influenced the creation of an entity — which steps and tool calls contributed to it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
entityId | path | string | required | Entity ID |
Responses
Returns entityId and provenance chain
{
"entityId": "string",
"steps": [
{}
]
}Internal error
{
"error": "internal error"
}List reasoning steps for a conversation. The conversation_id query parameter is required.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
conversation_id | query | string | required | Conversation ID |
Responses
Returns steps array
{
"steps": [
"..."
]
}Missing conversation_id
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Record a reasoning step taken by an agent. Captures the agent's thought process (reasoning), the action it decided to take (actionTaken), and optionally the result.
Request Body
{
"actionTaken": "string",
"conversationId": "string",
"reasoning": "string",
"result": "string"
}Responses
Returns id, conversationId, reasoning, actionTaken, result
{
"actionTaken": "string",
"conversationId": "string",
"id": "string",
"reasoning": "string",
"result": "string"
}Missing required fields
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Record a tool invocation made by an agent during a reasoning step. Optionally link to a step via stepId. Status values: "success", "error", "timeout".
Request Body
{
"durationMs": 0,
"input": "string",
"output": "string",
"status": "string",
"stepId": "string",
"toolName": "string"
}Responses
Returns id, stepId, toolName, status
{
"id": "string",
"status": "string",
"stepId": "string",
"toolName": "string"
}Missing required fields
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Get the full reasoning trace for a conversation — all steps and their tool calls, in order.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
conversationId | path | string | required | Conversation ID |
Responses
Returns conversationId, steps with nested toolCalls
{
"conversationId": "string",
"steps": [
"..."
],
"toolCalls": [
"..."
]
}Internal error
{
"error": "internal error"
}Query Console
Execute a read-only Cypher query directly against the tenant's graph database. Returns columns, rows, and query stats. Only read operations are permitted — write queries are rejected.
Request Body
{
"cypher": "string",
"params": {}
}Responses
Returns columns, rows, stats
{
"columns": [
"string"
],
"rows": [
{}
],
"stats": {}
}Invalid query or write operation attempted
{
"error": "internal error"
}Internal error
{
"error": "internal error"
}Connecting to the MCP Server
The MCP server uses Streamable HTTP transport and is available at https://memory.neo4jlabs.com/mcp. Pick your client below for a copy-paste config.
Claude Desktop's config does not accept a remote URL directly. Use the mcp-remote stdio bridge for static API keys, or open Settings -> Connectors -> Add custom connector for OAuth.
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"nams-memory": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://memory.neo4jlabs.com/mcp",
"--header",
"Authorization:Bearer ${NAMS_API_KEY}"
],
"env": {
"NAMS_API_KEY": "nams_YOUR_API_KEY"
}
}
}
}Save, fully quit Claude Desktop (Cmd/Ctrl+Q), reopen it. The nams-memory server appears under the tools (hammer) icon. Ask: 'List the NAMS memory tools you have.'
Windows note: keep 'Authorization:Bearer' with no space -- mcp-remote arguments break on whitespace there.
Anthropic's CLI coding agent. Native streamable-HTTP MCP and OAuth discovery.
Run from any project directory:
claude mcp add --transport http --scope project nams \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer nams_YOUR_API_KEY"
Start a session with `claude`, run `/mcp`, confirm `nams` is connected. Omit --header to use OAuth instead -- the first /mcp call opens a browser for PKCE.
OpenAI's terminal coding agent. Recent versions support remote streamable-HTTP MCP servers natively via TOML.
Edit ~/.codex/config.toml and add a server table.
[mcp_servers.nams] url = "https://memory.neo4jlabs.com/mcp" bearer_token_env_var = "NAMS_API_KEY"
Set NAMS_API_KEY in your shell, start a new Codex session, run `/mcp` to confirm `nams` is loaded. Older Codex installs are stdio-only -- wrap with `npx -y mcp-remote` instead.
Google's terminal coding agent. Use httpUrl (not url -- url silently routes through SSE, which this server does not expose).
Edit ~/.gemini/settings.json (or run `gemini mcp add -s user nams ...`):
{
"mcpServers": {
"nams": {
"httpUrl": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer $NAMS_API_KEY"
},
"timeout": 5000
}
}
}Set NAMS_API_KEY in your shell, restart any active Gemini session, run `/mcp`. Omit `headers` to trigger OAuth discovery on the server's 401 response.
AI code editor. Native streamable HTTP and OAuth discovery.
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project root):
{
"mcpServers": {
"nams": {
"url": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer ${env:NAMS_API_KEY}"
}
}
}
}Set NAMS_API_KEY in your shell, reload Cursor (Cmd/Ctrl+Shift+P -> Developer: Reload Window). Open Settings -> MCP and confirm `nams` is connected. Drop `headers` to use OAuth.
Codeium's Cascade-powered editor. Uses serverUrl (not url) for remote MCP endpoints.
Edit ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"nams": {
"serverUrl": "https://memory.neo4jlabs.com/mcp",
"headers": {
"Authorization": "Bearer ${env:NAMS_API_KEY}"
}
}
}
}Set NAMS_API_KEY in your shell, reload Windsurf or hit Cascade -> MCP servers -> Refresh. Confirm `nams` is connected. Omit `headers` for OAuth.
After connecting, your agent will have access to all 12 memory tools listed below.
Short-Term Memory
| Tool | Description | Parameters |
|---|---|---|
memory_create_conversation | Create a new conversation session for tracking agent interactions | user_id (optional) |
memory_add_messages | Add multiple messages to a conversation in bulk. Triggers async entity extraction. | conversation_id, messages (array of {role, content}) |
memory_get_context | Get the three-tier context: reflections, observations, and recent messages | conversation_id |
memory_search_messages | Search messages within a conversation by content | conversation_id, query |
Long-Term Memory
| Tool | Description | Parameters |
|---|---|---|
memory_search_entities | Search the knowledge graph for entities by name or type | query (optional), type (optional) |
memory_get_entity | Get details for a specific entity including its relationships | entity_id |
memory_add_entity | Add a new entity to the knowledge graph | name, type (person/organization/location/concept/tool/custom), description (optional) |
memory_get_entity_history | Get cross-conversation history — all messages that mention an entity | entity_id |
Reasoning Memory
| Tool | Description | Parameters |
|---|---|---|
memory_record_step | Record a reasoning step taken by an agent during a conversation | conversation_id, reasoning, action_taken, result (optional) |
memory_record_tool_call | Record a tool invocation made by an agent | tool_name, input, step_id (optional), output/status/duration_ms (optional) |
memory_get_trace | Get the full reasoning trace — all steps and tool calls | conversation_id |
memory_explain_decision | Get a detailed explanation of a reasoning step including tool calls and influenced entities | step_id |
Node Types
| Label | Description |
|---|---|
| Conversation | A conversation session between an agent and user |
| Message | A single message within a conversation (user, assistant, or system) |
| Entity | A named entity in the knowledge graph (person, org, location, etc.) |
| AgentStep | A reasoning step recording the agent's thought process |
| ToolCall | A record of a tool invocation made during a reasoning step |
| Observation | A compressed summary generated from a window of messages |
| Reflection | A higher-level insight synthesized from multiple observations |
Relationships
| Type | From | To |
|---|---|---|
HAS_MESSAGE | Conversation | Message |
HAS_STEP | Conversation | AgentStep |
USED_TOOL | AgentStep | ToolCall |
MENTIONS | Message | Entity |
INFLUENCED | AgentStep | Entity |
HAS_OBSERVATION | Conversation | Observation |
HAS_REFLECTION | Conversation | Reflection |
Entity Types
| Type | Description |
|---|---|
| person | People, contacts, team members |
| organization | Companies, teams, groups |
| location | Cities, countries, addresses |
| concept | Ideas, topics, technologies |
| tool | Software tools, APIs, services |
| custom | User-defined entity types |