Metadata-Version: 2.4
Name: comemo
Version: 1.1.0
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 SDK

Python SDK for [CoMemo](https://github.com/hasala/cognitive-memory) — a multi-module hybrid memory system powered by Pinecone and Neo4j.

## Installation

```bash
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.

```python
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="...",
)
```

### Core Memory

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

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

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

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

## Context Manager

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

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