Metadata-Version: 2.4
Name: solohq-memory
Version: 0.1.0
Summary: Context memory system for AI agents — persistent context graph with episodes, artifacts, relationships, and staleness tracking
Project-URL: Repository, https://github.com/whaleventure13/solohq-agent
Author: SoloHQ
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: apsw>=3.46
Requires-Dist: pydantic>=2.0
Requires-Dist: python-ulid>=3.0
Requires-Dist: sqlite-vec>=0.1.6
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-genai>=1.0; extra == 'google'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# solohq-memory

Core context memory library for AI agents. Persistent context graph with episodes, artifacts, relationships, and staleness tracking.

## Installation

```bash
pip install solohq-memory

# With LLM provider extras
pip install solohq-memory[anthropic]
pip install solohq-memory[openai]
pip install solohq-memory[google]
pip install solohq-memory[all]
```

## Quick Start

```python
from solohq_memory import (
    ContextMemoryManager,
    SqliteVecStorage,
)

# You need to provide LLM and embedding implementations
# that satisfy LLMProvider and EmbeddingProvider protocols

storage = SqliteVecStorage("memory.db", dimensions=1536)
manager = ContextMemoryManager(
    storage=storage,
    llm=your_llm_provider,
    embedder=your_embedding_provider,
)

# Classify a message to find or create a context
result = await manager.classify("Tell me about Python decorators")
context = result.context

# Record an episode
await manager.record_episode(
    context_id=context.id,
    user_message="Tell me about Python decorators",
    assistant_message="Decorators are a way to modify functions...",
)

# Search across all contexts
results = await manager.search("decorators", limit=5)
```

## Key Components

- **ContextMemoryManager** — main orchestrator for context operations
- **SqliteVecStorage** — SQLite + sqlite-vec storage with vector search
- **LLMClassifier** — 3-tier context routing: stable shortcut, embedding similarity, LLM fallback
- **ArtifactManager** — versioned content objects with rollback support
- **EpisodeRecorder** — conversation recording
- **BoundaryDetector** — topic shift detection (heuristics + LLM)
- **FileIndexer** — file indexing (on-disk references) and upload (full content)

## Interfaces

All providers are protocol-based and pluggable:

- `StorageProvider` — CRUD + vector search
- `LLMProvider` — `complete()` and `complete_json()`
- `EmbeddingProvider` — `embed()`, `embed_batch()`, `dimensions`
- `BlockStorageProvider` — session block persistence

## License

MIT
