Backend capabilities and data scope

This reference describes the released SDKs, Python neo4j-agent-memory 0.7.0 and TypeScript @neo4j-labs/agent-memory 0.5.0. Check the installed SDK’s API reference before using a method introduced after its release. NAMS is a continuously shipped service; /v1 identifies its REST API, not an SDK release.

Backend and language

Each section below covers one data type. Within it, each term names a backend and language, and its description gives that combination’s behavior for the operation.

Conversations and messages

Python with Bolt	Session-oriented writes and conversation readback
Python with NAMS	Create a conversation and pass its returned `id` as `session_id`. Use `bulk_add_messages` (no `add_messages_batch`, which raises `AttributeError`); `search_messages` requires a conversation ID; `list_sessions` and `get_conversation_summary` raise `NotSupportedError`; message metadata is not sent
TypeScript with NAMS REST	Create a conversation and use its returned ID

Entities and relationships

Entity writes/search

Python with Bolt	`add_entity` returns `(Entity, DeduplicationResult)`; client-side configuration. Message ingestion resolves extracted mentions against stored entities by default; see Tune entity resolution
Python with NAMS	`add_entity` returns `Entity`; server-managed extraction/deduplication
TypeScript with NAMS REST	`longTerm.addEntity` / `searchEntities`; server-managed processing

Client-created relationships

Python with Bolt	Supported with `add_relationship(source, target, relationship_type, …)`; `attributes` are returned on the model but not persisted in 0.7.0
Python with NAMS	Unsupported; inspect relationships produced by supported service processing
TypeScript with NAMS REST	Direct relationship-write methods are unsupported on REST

Geospatial search and graph adoption

Python with Bolt	Supported Bolt-specific operations
Python with NAMS	Not exposed. The `long_term` location methods are not defined (`AttributeError`). `get_locations` on the client and `adopt_existing_graph` on `client.schema` raise `NotSupportedError`
TypeScript with NAMS REST	Not exposed as equivalent REST operations

Preferences and facts

Python with Bolt	Supported; see the long-term API for user-scoped preference reads
Python with NAMS	Unsupported. The preference and fact methods NAMS defines raise `NotSupportedError`, with three exceptions that raise `TypeError`. The first is the positional Bolt form of `get_preferences_for`, passing a user. The second is the Bolt two-argument call to `supersede_preference`, whether written positionally or with the `old_preference_id` and `new_preference_id` keywords. The third is a Bolt call to `get_facts_about` that passes the `subject` or `limit` keyword: the NAMS method takes one positional `entity_name` and no keyword arguments. The category lookup `get_preferences_by_category` is not defined (`AttributeError`)
TypeScript with NAMS REST	Unsupported on REST; bridge compatibility methods are not hosted APIs

Reasoning

Python with Bolt	Traces, steps, and tool calls
Python with NAMS	Steps and tool calls are stored on a conversation; the trace lifecycle and outcome are held in the client instance. `list_traces`, `get_similar_traces`, `search_steps` and `get_tool_stats` raise `NotSupportedError`; `touched_entities` is dropped, and the tool-call hook and other tool-statistics methods are not defined (`AttributeError`). See NAMS lifecycle and operations
TypeScript with NAMS REST	Use `recordStep` and `getTraceByConversation`; legacy trace lifecycle calls are not REST operations

Extraction

Extraction configuration and local models

Python with Bolt	Client-side pipeline, providers and schema settings
Python with NAMS	Server-managed; `MemorySettings` `embedding`, `extraction` and `resolution` values are ignored with a `UserWarning`. Standalone extractors still run in your process
TypeScript with NAMS REST	Server-managed

Extraction readiness

Python with Bolt	The `long_term` accessor’s `wait_for_extraction` is a compatibility no-op; the `short_term` accessor has no `get_extraction_status`
Python with NAMS	Conversation status, and a bounded `wait_for_extraction` call on `long_term`
TypeScript with NAMS REST	Check the selected SDK’s `waitForExtraction` availability

Custom Cypher and platform accessors

Custom Cypher

Python with Bolt	Read queries through `client.query.cypher`; direct database access permits writes
Python with NAMS	Read-only service queries; not a workaround for unsupported writes
TypeScript with NAMS REST	Read-only service queries where exposed by the SDK

User registry, buffered writer, consolidation

Python with Bolt	Python `users`, `buffered`, and `consolidation` accessors
Python with NAMS	Not portable Bolt features; the accessors return a placeholder whose method calls raise `NotSupportedError`
TypeScript with NAMS REST	Not equivalent REST subclients

Ontologies and agent skills

Python with Bolt	Ontologies through `client.ontology` (`BoltOntology`), stored in your database as `:Ontology` and `:OntologyVersion` nodes. `import_` converts only local formats, and `migrate` runs synchronously; see Ontology API. Agent skills are a hosted service feature
Python with NAMS	Ontologies through the supported accessor; skills use REST/MCP, not invented SDK methods
TypeScript with NAMS REST	Ontology accessor where present in the selected artifact; skills use REST/MCP

The TypeScript test bridge is a development/conformance transport. Its operation names and successful test doubles do not establish a hosted REST feature. An integration adapter also cannot make an unsupported backend operation available.

For exact parameters, result shapes, defaults and exceptions, see Python API, TypeScript API, and REST API.

Hosted cleanup and retained resources

The selected NAMS contract provides conversation and entity deletion. It has no verified public DELETE route for reasoning steps, tool calls, skill runs or skills. Conversation deletion is not proof that these records or extracted entities were removed. Closing an SDK client deletes no service data.

Skills generation operates over the selected workspace, and a workspace data key does not grant workspace administration. Read-only Cypher cannot delete records. See the hosted conversation lesson and the Skills workflow for the cleanup each lesson performs and the resources it retains.

Identity and retrieval scope

Identifier or option Meaning and limit

Identifier or option	Meaning and limit
NAMS workspace	The service tenancy boundary. Selected by a workspace-bound key or the deployment’s supported workspace header. Separate from a conversation user identifier. See authentication.
Conversation/session ID	Selects a conversation for operations that implement that filter. The application must authorize access to the ID; knowing an ID is not authentication.
Python `user_identifier`	Accepted on particular writes and user-specific accessors. It is not a universal parameter and does not automatically filter entity, preference or trace searches.
TypeScript conversation `userId`	Conversation ownership metadata and an explicit list/filter input where supported. Reusing it does not resume a conversation or automatically retrieve all earlier conversations.
Python `memory.multi_tenant`	Requires user identifiers on particular implemented write paths. It is not database access control and does not add filters to every query.
TypeScript `namespace`	Currently unused by the implementation; provides no isolation.

NAMS workspace

The service tenancy boundary. Selected by a workspace-bound key or the deployment’s supported workspace header. Separate from a conversation user identifier. See authentication.

Conversation/session ID

Selects a conversation for operations that implement that filter. The application must authorize access to the ID; knowing an ID is not authentication.

Python user_identifier

Accepted on particular writes and user-specific accessors. It is not a universal parameter and does not automatically filter entity, preference or trace searches.

TypeScript conversation userId

Conversation ownership metadata and an explicit list/filter input where supported. Reusing it does not resume a conversation or automatically retrieve all earlier conversations.

Python memory.multi_tenant

Requires user identifiers on particular implemented write paths. It is not database access control and does not add filters to every query.

TypeScript namespace

Currently unused by the implementation; provides no isolation.

Bolt’s short_term.search_messages accepts a session_id argument but does not apply it in its Cypher search — do not treat that argument as an isolation guarantee.

get_context can likewise combine search results from wider scopes and is not an authorization boundary. For isolation, use a deliberately scoped read such as get_conversation, or separate authorized databases, and review each retrieval path. If a later SDK version adds the filter, verify it against the version you install.

long_term.get_preferences_for(user_identifier) follows a specific user’s preference relationship on Bolt. In contrast, search_preferences is a semantic search and is not automatically limited to that user. get_session_traces selects a session; similarity search over traces has a different scope. Entity knowledge can be shared within the selected database/workspace.

MCP surfaces

The Python self-hosted server’s core profile registers six tools. Its extended profile registers 16 tools with Bolt and 20 with NAMS, including four NAMS-specific tools. Registration does not mean every underlying operation works on every backend: core preference/fact tools can still raise NotSupportedError with NAMS. See self-hosted tool applicability.

The separately hosted NAMS MCP server has its own scope-dependent tool surface. Use tools/list for the authenticated principal and consult the hosted reference; a self-hosted registration count does not describe that service.

Conformance and limits

Bronze, Silver, Gold and Platinum are client TCK conformance labels, not NAMS pricing or access tiers. See service limits for request constraints and backend tradeoffs for choosing a deployment.

Preference associations can share a node: Bolt’s embedding-based duplicate lookup is global within a category. An existing preference can be linked to multiple users; superseding it affects those links. The scoped example disables embedding deduplication and uses explicit revision IDs.