Metadata-Version: 2.4
Name: comemo
Version: 1.2.1
Summary: Python SDK for CoMemo
Project-URL: Homepage, https://github.com/hasala/cognitive-memory-sdk
Project-URL: Documentation, https://github.com/hasala/cognitive-memory-sdk#readme
Project-URL: Issues, https://github.com/hasala/cognitive-memory-sdk/issues
Author: Hasala
License-Expression: MIT
Keywords: ai,cognitive,memory,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# CoMemo Python SDK

Python SDK for [CoMemo](https://github.com/hasala/cognitive-memory) — 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

```bash
pip install comemo
```

Install the driver for whichever backend you use:

```bash
# 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)

```python
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)

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

### Chroma + ArangoDB

```python
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

```python
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

```python
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

```python
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)

```python
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

```python
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

```python
# 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

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

### Maintenance

```python
# 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

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

## Error Handling

```python
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
