LongTermMemory API reference

Entity, preference, fact, relationship, provenance, and location operations exposed through client.long_term. The main signatures describe the bolt implementation; hosted differences are listed separately.

Signatures below show types, keyword-only arguments (*), and defaults. They are reference declarations; the examples show calls to execute.

See Backend capabilities for availability and data scope. This page is a short overview and index; each subsystem has its own page.

Overview

The default POLE+O entity types are PERSON, OBJECT, LOCATION, EVENT, and ORGANIZATION. Subtypes and custom types depend on the configured domain schema.

# Bolt: add_entity returns an entity and its deduplication result.
person, dedup = await client.long_term.add_entity(
    "John Smith", "PERSON", subtype="INDIVIDUAL"
)
company, _ = await client.long_term.add_entity(
    "Acme Corp", "ORGANIZATION", subtype="COMPANY"
)
await client.long_term.add_relationship(person, company, "WORKS_AT")
for entity in await client.long_term.search_entities("software company"):
    print(entity.name, entity.metadata.get("similarity"))

Search methods return models, not (model, score) tuples. Bolt semantic-search scores are stored in metadata["similarity"]. Entity search is not user-scoped; see the backend capability and scope reference before designing tenancy.

On this subsystem

  • Entity and relationship operations — add_entity, get_entity_by_name, search_entities, add_relationship, get_related_entities, get_entity_relationships, and the Entity/Relationship models.

  • Preference and fact operations — add_preference, get_preferences_for, search_preferences, supersede_preference, add_fact, get_facts_about, search_facts, and the Preference/Fact models.

  • Deduplication and provenance — ingest-time duplicate detection (find_potential_duplicates, merge_duplicate_entities, review_duplicate) and extraction provenance (register_extractor, link_entity_to_message, get_entity_provenance).

  • Geospatial operations and NAMS behavior — location search/geocoding, get_context, and the NAMS wrapper differences table.

Constructor

Bolt only. MemoryClient builds this store for you; it passes its resolver, its resolved ontology and validation mode, and a DeduplicationConfig derived from settings.resolution. The signature matters when you construct the store directly.

def LongTermMemory(
    client: Neo4jClient,
    embedder: Embedder | None=None,
    extractor: EntityExtractor | None=None,
    resolver: EntityResolver | None=None,
    geocoder: Geocoder | None=None,
    enrichment_service: BackgroundEnrichmentService | None=None,
    entity_types: list[str] | None=None,
    strict_types: bool=False,
    deduplication: DeduplicationConfig | None=None,
    *,
    multi_tenant: bool=False,
    ontology: OntologyDocument | None=None,
    validation_mode: Literal['permissive', 'strict']='permissive',
): ...
Parameter Description

resolver

Resolver used by add_entity. When it is an OntologyResolver, the bolt default, the duplicate check delegates to it, so add_entity and message ingestion share one normalization, one blocking strategy, and one set of thresholds. Any other resolver keeps the embedding-similarity check.

deduplication

Bands for the embedding-similarity check. Derive it with DeduplicationConfig.from_resolution_config(settings.resolution) so the two paths cannot drift; see DeduplicationConfig.

entity_types, strict_types

Legacy type check: with strict_types=True, add_entity raises ValueError for a base type outside entity_types. Independent of the ontology’s validation mode.

ontology

The effective ontology, used for strict-mode validation and for mapping type and subtype pairs onto declared labels.

validation_mode

strict makes add_entity and add_relationship raise ValidationError; permissive writes anyway. Ignored when ontology is None.

Strict-mode validation

With validation_mode="strict" and an ontology configured, these writes raise neo4j_agent_memory.core.exceptions.ValidationError, whose details carries the offending type, labels, and ontology name:

Rejected Raised by

An entity whose type and subtype the ontology declares no label for. A declared base type still validates when only the subtype is unknown.

add_entity

A relationship type the ontology does not declare

add_relationship

An endpoint whose stored type maps onto no declared label

add_relationship

An endpoint pair the ontology does not permit for that relationship type (OntologyDocument.permits)

add_relationship

An ontology that declares no relationships, such as the ad-hoc document built from schema_config.entity_types, places no constraint on add_relationship.

See also