Schema objects reference

Inventory of the constraints, regular indexes, text indexes, vector indexes, and point indexes that the bolt backend attempts to create on connection. NAMS manages its schema on the service; client.schema is not supported there. Use this page to answer "what schema changes will this library make to my Neo4j database?" before deploying.

Schema creation is performed by neo4j_agent_memory.graph.schema.SchemaManager.setup_all(), which runs as part of MemoryClient.connect(). Existing constraints/indexes with the same name are skipped; the operation is idempotent.

setup_all() also runs a one-time data backfill that copies the legacy relation_type property of RELATED_TO relationships into type, the canonical relationship-name property since 0.7. It runs once per database: completion is recorded on a (:SchemaMigration {name: "relation_type_backfill"}) node, and later connects skip it. A failure is logged rather than raised, and the backfill is retried on the next connect. Set schema_config.backfill_relation_types=False to skip it and run the equivalent query yourself in batches on a very large graph.

A second one-time backfill, recorded as (:SchemaMigration {name: "entity_keys_backfill"}) and gated by the same setting, fills the entity lookup keys that entity resolution reads: name_key (the lower-cased name) and surface_keys (every surface form — name, canonical name and aliases — lower-cased between | delimiters). Every library write keeps both up to date. An entity written by your own Cypher has neither until you set them, and resolution’s exact-name and name-prefix lookups cannot find it.

The authoritative source is src/neo4j_agent_memory/graph/schema.py. This page is a human-readable reference to the schema objects the library creates, but consult that file for the complete current inventory used in deployments.

Unique constraints

Name Label Property Purpose

conversation_id

Conversation

id

Unique conversation identifier.

message_id

Message

id

Unique message identifier.

entity_id

Entity

id

Unique entity identifier across all subtypes.

preference_id

Preference

id

Unique preference identifier.

fact_id

Fact

id

Unique fact identifier.

reasoning_trace_id

ReasoningTrace

id

Unique reasoning-trace identifier.

reasoning_step_id

ReasoningStep

id

Unique reasoning-step identifier.

tool_name

Tool

name

One Tool node per unique tool name (used for aggregated stats).

tool_call_id

ToolCall

id

Unique tool-call identifier.

user_identifier

User

identifier

Unique user identifier (multi-tenancy).

consolidation_run_id

ConsolidationRun

id

Unique consolidation-job run identifier.

memory_read_audit_id

MemoryReadAudit

id

Unique memory-read audit event identifier.

ontology_id

Ontology

id

Unique stored-ontology identifier (bolt client.ontology).

ontology_version_id

OntologyVersion

id

Unique ontology-version identifier.

ontology_lock_id

OntologyLock

id

Backs the single lock node that serializes concurrent ontology activations.

Regular indexes

Lookup indexes for common filter / equality queries.

Name Label Property Purpose

conversation_session_idx

Conversation

session_id

Look up conversations by session.

conversation_archived_idx

Conversation

archived

Filter active vs. archived conversations.

message_timestamp_idx

Message

timestamp

Order messages chronologically.

message_role_idx

Message

role

Filter messages by role (user / assistant / system / tool).

entity_type_idx

Entity

type

Filter entities by POLE+O (or custom) type.

entity_name_idx

Entity

name

Look up entities by display name.

entity_canonical_idx

Entity

canonical_name

Look up entities by deduplicated canonical name.

entity_name_key_idx

Entity

name_key

Entity resolution: names starting with a mention’s first token.

preference_category_idx

Preference

category

Filter preferences by category.

trace_session_idx

ReasoningTrace

session_id

Reasoning traces for a session.

trace_success_idx

ReasoningTrace

success

Successful vs. failed traces.

trace_error_kind_idx

ReasoningTrace

error_kind

Filter failed traces by error classification.

consolidation_run_kind_idx

ConsolidationRun

kind

Filter consolidation runs by kind.

memory_read_audit_kind_idx

MemoryReadAudit

kind

Filter memory-read audit events by kind.

tool_call_status_idx

ToolCall

status

Filter tool calls by status.

ontology_name_idx

Ontology

name

Look up stored ontologies by name.

Text indexes

Back the CONTAINS and ENDS WITH lookups of entity resolution, which runs on every ingested message.

Name Label Property Purpose

entity_surface_keys_idx

Entity

surface_keys

Entity resolution: exact match on any surface form (name, canonical name, alias).

entity_name_key_text_idx

Entity

name_key

Entity resolution: names ending with a mention’s last token.

Vector indexes

Created with the embedding dimensions configured at construction time (SchemaManager(client, vector_dimensions=…​)). Default is 1536.

Vector-index creation exceptions are currently suppressed, including failures unrelated to server version. A successful connection therefore does not prove every index exists or is online. Point-index creation also suppresses errors. Inspect SHOW INDEXES when validating deployment permissions and semantic/geospatial query behavior.

After setup, MemoryClient validates the dimensions of existing managed vector indexes against the configured embedder. Mismatches raise EmbeddingDimensionMismatchError; unrelated index names are not checked. Changing a model requires the migration workflow, not just changing this setting.

Name Label Property Purpose

message_embedding_idx

Message

embedding

Semantic search over message content.

entity_embedding_idx

Entity

embedding

Semantic search over entity descriptions.

preference_embedding_idx

Preference

embedding

Semantic search over preferences.

fact_embedding_idx

Fact

embedding

Semantic search over facts.

task_embedding_idx

ReasoningTrace

task_embedding

Search past reasoning traces by task similarity.

step_embedding_idx

ReasoningStep

embedding

Semantic search over individual reasoning steps (used by search_steps).

Point indexes

Created for geospatial queries on Location entities.

Name Label Property Purpose

entity_location_idx

Entity

location

Geospatial proximity queries (point.distance, bounding box).

Removing the schema

SchemaManager.drop_all() removes every constraint and index whose name starts with one of conversation_, message_, entity_, preference_, fact_, reasoning_, trace_, tool_, task_, step_, user_, consolidation_, memory_read_, or ontology_. It does not delete data, but its prefix matching can also remove application-owned schema objects using those prefixes. Inspect the current inventory before deliberately calling it.

async with MemoryClient(settings) as client:
    await client.schema.drop_all()

See also