ShortTermMemory API reference

Conversation and message operations exposed through client.short_term. Signatures in the bolt sections describe ShortTermMemory; the NAMS table identifies hosted differences.

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

message = await client.short_term.add_message(
    session_id="example", role="user", content="Hello, world!"
)
conversation = await client.short_term.get_conversation("example")
for stored in conversation.messages:
    print(stored.role.value, stored.content)

The example uses bolt, where a session name can create a conversation implicitly. On NAMS, call create_conversation first and use its returned ID.

On this subsystem

  • Conversation and message operations — add_message, add_messages_batch, get_conversation, delete_message, the NAMS conversation operations (create_conversation, list_conversations, bulk_add_messages, get_observations, get_reflections, get_extraction_status), and the Message/Conversation/ExtractionStatus models.

  • Message search and context — search_messages and get_context.

  • Sessions, summaries, and maintenance — list_sessions, clear_session, get_conversation_summary, migrate_message_links, generate_embeddings_batch, extract_entities_from_session, and the SessionInfo/ConversationSummary models.

Constructor

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

def ShortTermMemory(
    client: Neo4jClient,
    embedder: Embedder | None=None,
    extractor: EntityExtractor | None=None,
    *,
    multi_tenant: bool=False,
    default_llm_provider: LLMProvider | None=None,
    ontology: OntologyDocument | None=None,
    validation_mode: Literal['permissive', 'strict']='permissive',
    resolver: EntityResolver | None=None,
    resolution_config: ResolutionConfig | None=None,
): ...
Parameter Description

client

Connected Neo4j client.

embedder

Optional embedder for message embeddings and extracted entity names.

extractor

Optional entity extractor.

multi_tenant

When True, writes require user_identifier=.

default_llm_provider

Optional LLM provider used by get_conversation_summary when no summarizer is passed.

ontology

The effective ontology. Extracted relations the ontology does not permit are dropped before storage, in either validation mode.

validation_mode

strict also drops extracted entities whose type and subtype the ontology does not declare, with a warning, along with any relation that referenced them. permissive stores them.

resolver

Resolver for the ingestion path. Only an OntologyResolver resolves during ingestion; any other resolver, or None, stores one node per distinct surface form.

resolution_config

Resolution settings. resolve_on_ingest=False turns ingest-time resolution off.

Entity extraction on ingest

When an extractor is configured, add_message, add_messages_batch, and extract_entities_from_session persist entities through one path. Since 0.7 it:

  1. filters invalid entity names (stopwords, bare numbers, single characters),

  2. enforces the ontology: it always drops forbidden relations, and in strict mode also drops undeclared entities,

  3. embeds the mention names in one batch when an embedder is configured, so new entities are searchable and resolution reuses the vectors,

  4. resolves the message’s mentions as one episode, when resolution.resolve_on_ingest is True and the resolver is an OntologyResolver, and

  5. writes each mention by its band: merged reuses the matched node and appends the surface form to its aliases; review creates the node plus a pending SAME_AS edge to the match, which long_term.find_potential_duplicates returns; created creates the node.

Each MENTIONS edge points at the entity id the database holds, including when the entity MERGE matched a pre-existing node. A resolution failure is logged and the mentions are stored unresolved; resolution never blocks the write. See Tune entity resolution and Resolution configuration.

See also