comemo 1.2.1

Python SDK for CoMemo

CoMemo Python SDK

Python SDK for CoMemo — a multi-module hybrid memory system for AI applications.

Bring your own databases. CoMemo works with 7 vector stores and 7 graph stores — Pinecone, Qdrant, Weaviate, Chroma, Milvus, pgvector, FAISS, Neo4j, Memgraph, ArangoDB, Amazon Neptune, TigerGraph, GraphDB, and NetworkX.

Installation

pip install comemo

Install the driver for whichever backend you use:

# Vector stores
pip install pinecone-client      # Pinecone
pip install qdrant-client        # Qdrant
pip install weaviate-client      # Weaviate
pip install chromadb             # Chroma
pip install pymilvus             # Milvus / Zilliz
pip install psycopg2-binary pgvector  # pgvector (Postgres)
pip install faiss-cpu            # FAISS (local)

# Graph stores
pip install neo4j                # Neo4j, Memgraph, Amazon Neptune
pip install python-arango        # ArangoDB
pip install pyTigerGraph         # TigerGraph
pip install SPARQLWrapper        # GraphDB (Ontotext)
# NetworkX — no extra install needed (pure Python, local)

Quick Start

Pinecone + Neo4j (default)

from comemo import MemoryClient

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

Qdrant + NetworkX (fully local, no cloud accounts)

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="qdrant",
    qdrant_url="http://localhost:6333",
    qdrant_collection="memories",
    graph_store="networkx",
)

Chroma + ArangoDB

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="chroma",
    chroma_collection="memories",
    chroma_host="localhost",       # omit for in-process mode
    graph_store="arangodb",
    arangodb_url="http://localhost:8529",
    arangodb_username="root",
    arangodb_password="...",
)

Weaviate + Memgraph

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="weaviate",
    weaviate_url="http://localhost:8080",
    weaviate_collection="Memory",
    graph_store="memgraph",
    neo4j_uri="bolt://localhost:7687",
)

Milvus + TigerGraph

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="milvus",
    milvus_uri="http://localhost:19530",
    milvus_collection="memories",
    graph_store="tigergraph",
    tigergraph_host="https://my-instance.i.tgcloud.io",
    tigergraph_username="admin",
    tigergraph_password="...",
)

pgvector + Amazon Neptune

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="pgvector",
    pgvector_dsn="postgresql://user:pass@localhost:5432/mydb",
    graph_store="neptune",
    neo4j_uri="bolt://my-cluster.neptune.amazonaws.com:8182",
)

FAISS + GraphDB (fully local)

client = MemoryClient(
    llm_api_key="sk-...",
    vector_store="faiss",
    faiss_index_path="/tmp/faiss-index",   # optional persistence
    graph_store="graphdb",
    graphdb_url="http://localhost:7200",
    graphdb_repository="cognitivememory",
)

Supported Backends

Vector Stores

Backend	vector_store	Required fields
Pinecone	"pinecone"	pinecone_api_key, pinecone_index
Qdrant	"qdrant"	qdrant_url, qdrant_collection
Weaviate	"weaviate"	weaviate_url, weaviate_collection
Chroma	"chroma"	chroma_collection
Milvus / Zilliz	"milvus"	milvus_uri, milvus_collection
pgvector	"pgvector"	pgvector_dsn
FAISS (local)	"faiss"	(none — ephemeral by default)

Graph Stores

Backend	graph_store	Required fields
Neo4j	"neo4j"	neo4j_uri, neo4j_username, neo4j_password
Memgraph	"memgraph"	neo4j_uri (bolt URI)
Amazon Neptune	"neptune"	neo4j_uri (Neptune bolt URI)
ArangoDB	"arangodb"	arangodb_url, arangodb_username, arangodb_password
TigerGraph	"tigergraph"	tigergraph_host, tigergraph_username, tigergraph_password
GraphDB	"graphdb"	graphdb_url
NetworkX (local)	"networkx"	(none — ephemeral by default)

Core Operations

Add memory

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

Retrieve

# Simple
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 — full scoring breakdown
result = client.retrieve_advanced(
    "john", "chat_01", "career and hobbies",
    top_k=10, expand_context=True, expand_graph=True, min_score=0.3,
)
for m in result.memories:
    print(f"{m.fact} | sem={m.semantic_similarity:.2f} graph={m.graph_relevance:.2f}")

# With LLM summary
summary = client.retrieve_summary("john", "chat_01", "Tell me about John")
print(summary.summary)

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

Delete

client.delete_memory("mem_abc123")
client.delete_session_memories("john", "chat_01")
client.delete_user_memories("john")

Maintenance

# Auto decay + forgetting + summarization
client.run_maintenance("john")

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

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

Context Manager

with MemoryClient(llm_api_key="sk-...", vector_store="faiss", graph_store="networkx") as client:
    client.add_memory("alice", "s1", "I love hiking")

Error Handling

from comemo import MemoryClient, ValidationError, AuthenticationError, ServerError

try:
    client.retrieve("john", "chat_01", "")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
except ServerError as e:
    print(f"Server error: {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 by ID
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 full scoring
list_memories(user_id, query, top_k=10)	List memories across all sessions
retrieve_summary(user_id, session_id, query, top_k=5)	Retrieve with LLM-generated summary
run_maintenance(user_id, tasks=None, dry_run=False)	Decay, forgetting, summarization
health()	Health check

License

MIT