Python SDK

nm.ingest(user_id, role, content, ...)

Stores a conversation message to long-term memory. When auto_extract is enabled, facts, episodes, and knowledge graph triples are extracted in the background.

Parameters

Returns

Message -- The stored message object with generated ID and timestamp.

Example

msg = await nm.ingest(
    user_id="user-123",
    role="user",
    content="I just switched from PyCharm to VS Code",
    session_id="session-456",
    metadata={"source": "chat"}
)
print(f"Stored: {msg.id}")

nm.recall(user_id, query, ...)

Hybrid memory search combining vector similarity, BM25 full-text search, and knowledge graph traversal. Returns merged results ranked by combined score.

Parameters

Returns

dict -- {"vector_results": [...], "graph_results": [...], "merged": [...], "inferred_context": str, "context_confidence": float}

Example

results = await nm.recall(
    user_id="user-123",
    query="programming preferences",
    limit=10,
    memory_type="fact"
)

for m in results["merged"]:
    print(f"[{m['memory_type']}] {m['content']} (score: {m['score']:.2f})")

print(f"Context: {results['inferred_context']}")
print(f"Confidence: {results['context_confidence']:.2f}")

nm.digest(user_id, ...)

Analyzes un-reflected memories and synthesizes behavioral traits. Discovers patterns, preferences, and tendencies from accumulated memory data.

Parameters

Returns

dict | None -- {"memories_analyzed": int, "traits_generated": int, "traits": [...]} or None if background=True.

Example

result = await nm.digest(user_id="user-123", batch_size=100)

print(f"Analyzed: {result['memories_analyzed']} memories")
print(f"Generated: {result['traits_generated']} traits")
for trait in result["traits"]:
    print(f"  - {trait['content']} (stage: {trait['stage']})")

nm.list_memories(user_id, ...)

List memories with pagination. Useful for building memory browsers or audit views.

Parameters

Returns

tuple[int, list] -- (total_count, list_of_memories)

Example

total, memories = await nm.list_memories(
    user_id="user-123",
    memory_type="fact",
    limit=20,
    offset=0
)
print(f"Showing {len(memories)} of {total} facts")

nm.update_memory(memory_id, user_id, ...)

Update an existing memory's content or type. If content is changed, the embedding vector is automatically regenerated.

Parameters

Returns

Memory | None -- The updated memory object, or None if not found.

Example

updated = await nm.update_memory(
    memory_id="mem-abc123",
    user_id="user-123",
    content="Prefers VS Code with Vim keybindings"
)
if updated:
    print(f"Updated: {updated.content}")

nm.delete_memory(memory_id, user_id)

Permanently delete a memory by ID. Returns True if the memory was found and deleted.

Parameters

Returns

bool -- True if deleted, False if not found.

Example

deleted = await nm.delete_memory(
    memory_id="mem-abc123",
    user_id="user-123"
)
print("Deleted" if deleted else "Not found")

nm.get_user_traits(user_id, ...)

Retrieve active behavioral traits for a user. Traits evolve through stages: trend, candidate, emerging, established, core. Dissolved traits are excluded by default.

Parameters

Returns

list[dict] -- List of trait objects with content, stage, confidence, and metadata.

Example

traits = await nm.get_user_traits(
    user_id="user-123",
    min_stage="established",
    subtype="preference"
)
for trait in traits:
    print(f"[{trait['stage']}] {trait['content']}")

nm.profile_view(user_id)

Get an assembled user profile combining extracted facts, behavioral traits, and recent mood indicators. Useful for providing context to AI assistants.

Parameters

Returns

dict -- {"facts": [...], "traits": [...], "recent_mood": str | None}

Example

profile = await nm.profile_view(user_id="user-123")

print("Facts:")
for fact in profile["facts"]:
    print(f"  - {fact}")

print("Traits:")
for trait in profile["traits"]:
    print(f"  - {trait['content']} ({trait['stage']})")

print(f"Mood: {profile['recent_mood']}")

nm.reflect(user_id, force=False)

Manually trigger the reflection cycle. Analyzes recent memories and creates, updates, or dissolves traits based on observed patterns.

Parameters

Returns

dict -- {"triggered": bool, "traits_created": int, "traits_updated": int, "traits_dissolved": int}

Example

result = await nm.reflect(user_id="user-123", force=True)
if result["triggered"]:
    print(f"Created: {result['traits_created']}")
    print(f"Updated: {result['traits_updated']}")
    print(f"Dissolved: {result['traits_dissolved']}")

nm.init(schema=None)

Initialize database tables and extensions (pgvector, pg_search). Must be called once before using any other methods. Optionally specify a custom schema name.

Parameters

Returns

None

Example

nm = NeuroMemory(...)
await nm.init()  # Creates tables if they don't exist

nm.close()

Close the database connection pool and release all resources. Should be called when the NeuroMemory instance is no longer needed.

Returns

None

Example

await nm.close()  # Always clean up when done