Metadata-Version: 2.4
Name: zeno-memory
Version: 1.0.2
Summary: Zeno memory protocols, context-bound handles, and SQLite defaults.
Project-URL: Homepage, https://github.com/nkootstra/zeno
Project-URL: Repository, https://github.com/nkootstra/zeno
Project-URL: Issues, https://github.com/nkootstra/zeno/issues
Project-URL: Changelog, https://github.com/nkootstra/zeno/blob/main/CHANGELOG.md
Author: Niels Kootstra
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,memory,sqlite,vectorstore,zeno
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiosqlite<1,>=0.19
Requires-Dist: zeno-core
Description-Content-Type: text/markdown

# zeno-memory

Memory protocols, per-turn view handles, and SQLite-backed defaults for the
[Zeno](https://github.com/nkootstra/zeno) framework.

## Install

```bash
uv add 'zeno-framework[memory]'
```

## What's in here

- Protocols: `SessionStore`, `UserMemoryStore`, `KnowledgeStore`,
  `ConversationStore`, `VectorStore`.
- Per-turn handles: `MemoryView`, `UserMemoryView`, `KnowledgeView`,
  `ConversationHandle`, `SessionHandle`.
- SQLite defaults: `SqliteSessionStore`, `SqliteUserMemoryStore`,
  `SqliteConversationStore`.
- Composer: `ThreeLayer` (session + user memory + knowledge + conversation).
- Adapter: `VectorBackedUserMemoryStore` — wraps any `KnowledgeStore`
  to make user memory semantically searchable.

## Wiring

```python
from pathlib import Path

from zeno.app import ZenoApp
from zeno.memory import ThreeLayer
from zeno.memory.sqlite.conversation_store import SqliteConversationStore
from zeno.memory.sqlite.session_store import SqliteSessionStore
from zeno.memory.sqlite.user_memory_store import SqliteUserMemoryStore

data = Path.home() / ".zeno"
data.mkdir(parents=True, exist_ok=True)

# `knowledge=` is a `KnowledgeStore` from a vector backend — see
# `zeno-chroma` or `zeno-qdrant` for concrete adapters. The example below
# uses `SqliteUserMemoryStore` for user memory; swap in
# `VectorBackedUserMemoryStore(knowledge_store=...)` to make user memory
# semantically searchable.
memory = ThreeLayer(
    session=SqliteSessionStore(data / "sessions.db"),
    user_memory=SqliteUserMemoryStore(data / "user_memory.db"),
    knowledge=...,  # ChromaKnowledgeStore | QdrantKnowledgeStore | …
    conversation=SqliteConversationStore(data / "conversations.db"),
)

app = ZenoApp(agent=..., memory=memory, channels=..., provider=...)
```

`ZenoApp` calls `memory.view_for(user_id=, channel=, thread_key=)` once per
turn and binds the resulting `MemoryView` into `Ctx`. Tools use
`ctx.memory.user`, `ctx.memory.knowledge`, `ctx.memory.session`, and
`ctx.memory.conversation` without ever seeing the underlying store.

## Choosing a `UserMemoryStore`

| Store | Use when |
| ----- | -------- |
| `SqliteUserMemoryStore` | You want exact-match recall on stored facts. Cheap, no embedding model required. |
| `VectorBackedUserMemoryStore(knowledge_store=…)` | You want semantic recall (e.g. "what did the user say about their job?"). Reuses the same vector backend you wired for `knowledge`. |

Both implement the same `UserMemoryStore` protocol — swap freely without
changing tool code.

## ConversationStore (provider portability)

Non-Claude providers (e.g. `OpenAIProvider`) write each turn's assistant,
tool, and user messages through `ConversationStore` so the next turn has
prior context. `ClaudeSDKProvider` does not use it — the SDK owns its own
session history.

## Vector backends

Concrete `KnowledgeStore` adapters live in sibling packages:

- [`zeno-chroma`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-chroma) — ChromaDB-backed.
- [`zeno-qdrant`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-qdrant) — Qdrant-backed.

See also: [`zeno-core`](https://github.com/nkootstra/zeno/tree/main/packages/zeno-core)
for `Ctx`, `@tool`, and the `MemoryBinderProtocol`.

Part of the [Zeno framework](https://github.com/nkootstra/zeno).
