comemo 1.0.1

Python SDK for CoMemo

CoMemo SDK

Python SDK for CoMemo — a multi-module hybrid memory system powered by Pinecone and Neo4j.

Installation

pip install comemo

Quick Start

Each client requires your own infrastructure credentials. All operations use your own Pinecone index, Neo4j database, and LLM API key.

from comemo import MemoryClient

client = MemoryClient(
    llm_api_key="sk-your-openai-key",
    model="gpt-4o-mini",
    pinecone_api_key="pc-...",
    pinecone_index="my-memory-index",
    neo4j_uri="neo4j+s://xxx.databases.neo4j.io",
    neo4j_username="neo4j",
    neo4j_password="...",
)

Optional fields:

client = MemoryClient(
    ...,
    pinecone_namespace="tenant-a",   # Multi-tenant within one Pinecone index
    neo4j_database="mydb",           # Neo4j database name (defaults to "neo4j")
    base_url="https://xvert.io",     # API base URL
    timeout=30,                       # Request timeout in seconds
)

Core Memory

# Add a memory
result = client.add_memory("john", "chat_01", "I work at Google as a software engineer")
print(result.status)     # "success"
print(result.action)     # "NEW"
print(result.memory_id)  # "mem_abc123"

# Delete all user memories
client.delete_user_memories("john")

# Delete session memories
client.delete_session_memories("john", "chat_01")

# Delete a single memory
client.delete_memory("mem_abc123")

Retrieval

# Simple retrieve
result = client.retrieve("john", "chat_01", "Where does John work?", top_k=5)
for m in result.memories:
    print(f"{m.fact} (score: {m.score:.2f})")

# Advanced retrieve with full scoring breakdown
result = client.retrieve_advanced(
    user_id="john",
    session_id="chat_01",
    query="career and hobbies",
    top_k=10,
    expand_context=True,
    expand_graph=True,
    min_score=0.3,
    reinforce=True,
)
for m in result.memories:
    print(f"{m.fact} | semantic={m.semantic_similarity:.2f} graph={m.graph_relevance:.2f}")

# List memories across all sessions
result = client.list_memories("john", query="work", top_k=10)

# Retrieve with LLM summary
summary = client.retrieve_summary("john", "chat_01", "Tell me about John's career")
print(summary.summary)

Maintenance

# Run maintenance tasks (decay, forgetting, summarization)
result = client.run_maintenance("john")

# Selective tasks
result = client.run_maintenance(
    "john",
    tasks={"decay": True, "forgetting": True, "summarization": False},
)

# Dry run
result = client.run_maintenance("john", dry_run=True)

System

health = client.health()
print(health.status)        # "healthy"
print(health.version)       # "6.0.0"
print(health.architecture)  # "Multi-Module Hybrid Memory (Multi-Tenant)"

Context Manager

with MemoryClient(
    llm_api_key="sk-...",
    pinecone_api_key="pc-...",
    pinecone_index="my-index",
    neo4j_uri="bolt://localhost:7687",
    neo4j_username="neo4j",
    neo4j_password="...",
) as client:
    client.add_memory("john", "chat_01", "My favorite color is blue")

Error Handling

from comemo import MemoryClient, ValidationError, NotFoundError

try:
    client.retrieve("john", "chat_01", "")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except NotFoundError as e:
    print(f"Not found: {e.message}")

All Methods

Method	Description
add_memory(user_id, session_id, text)	Extract facts and store as memories
delete_memory(memory_id)	Delete a single memory
delete_user_memories(user_id)	Delete all memories for a user
delete_session_memories(user_id, session_id)	Delete all memories for a session
retrieve(user_id, session_id, query, top_k=5)	Simple retrieval
retrieve_advanced(user_id, session_id, query, ...)	Advanced retrieval with scoring
list_memories(user_id, query, top_k=10)	List memories across sessions
retrieve_summary(user_id, session_id, query, top_k=5)	Retrieve with LLM summary
run_maintenance(user_id, tasks=None, dry_run=False)	Run tenant-scoped maintenance
health()	Health check

License

MIT