Metadata-Version: 2.4
Name: zeno-chroma
Version: 1.0.2
Summary: ChromaDB-backed KnowledgeStore adapter for Zeno.
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,chromadb,embeddings,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: chromadb<1,>=0.5
Requires-Dist: zeno-core
Requires-Dist: zeno-memory
Description-Content-Type: text/markdown

# zeno-chroma

[ChromaDB](https://www.trychroma.com/)-backed `KnowledgeStore`
adapter for [Zeno](https://github.com/nkootstra/zeno).

Persists facts and documents in a local Chroma collection with each
row stamped by `user_id` so multi-tenant isolation is enforced at
query time via Chroma's `where` filter rather than post-fetch
filtering. Plugs into the `ThreeLayer` memory binder as the
`knowledge` and (optionally) the `user_memory` backing.

## Install

```bash
uv add 'zeno-framework[chroma]'
# or, without the AI package:
uv add zeno-chroma
```

## Features

- Persistent local store via `chromadb.PersistentClient` — no server
  to run, just a directory
- `user_id`-scoped search using Chroma's `where` filter (S7 isolation
  is structural, not advisory)
- Cosine similarity, distance → similarity score conversion
  (`1.0 - distance`, clamped to `[0, 1]`)
- Synchronous Chroma client wrapped in `asyncio.to_thread` so
  embeddings and queries don't block the event loop
- Default Chroma embedding function; pass `embedding_function=` to
  override
- Pairs with `VectorBackedUserMemoryStore` to also serve user-memory
  reads/writes from the same collection

## Minimal usage

```python
import asyncio
from pathlib import Path

from zeno.agent import Agent
from zeno.app import ZenoApp
from zeno.builtin_tools import recall, remember
from zeno.channels.cli import CliChannel
from zeno.chroma import ChromaKnowledgeStore
from zeno.memory.sqlite.conversation_store import SqliteConversationStore
from zeno.memory.sqlite.session_store import SqliteSessionStore
from zeno.memory.three_layer import ThreeLayer
from zeno.memory.vector_backed.user_memory_store import VectorBackedUserMemoryStore
from zeno.testing import FakeProvider

async def main() -> None:
    data_dir = Path("./.zeno")
    data_dir.mkdir(exist_ok=True)

    knowledge = ChromaKnowledgeStore(persist_dir=data_dir / "chroma")
    memory = ThreeLayer(
        session=SqliteSessionStore(data_dir / "sessions.db"),
        user_memory=VectorBackedUserMemoryStore(knowledge_store=knowledge),
        knowledge=knowledge,
        conversation=SqliteConversationStore(data_dir / "conversations.db"),
    )

    app = ZenoApp(
        agent=Agent(
            name="root",
            instructions="Use `recall` to look things up and `remember` to store facts.",
            tools=[recall, remember],
        ),
        channels=[CliChannel()],
        provider=FakeProvider(),
        memory=memory,
    )
    await app.run()

asyncio.run(main())
```

The first call to `remember` writes a row tagged with the active
`user_id`. Subsequent `recall` calls only see rows that user inserted —
cross-user isolation is enforced by the `where={"user_id": ...}`
filter on every query.

## Testing

```bash
uv run pytest packages/zeno-chroma
```

Tests run against a temporary Chroma directory so no global state
leaks between cases. The contract suite shared with `zeno-qdrant`
guarantees both adapters honour the same `KnowledgeStore` semantics.

## See also

- [`zeno-qdrant`](../zeno-qdrant/README.md) — the other first-party `KnowledgeStore` adapter.
- [`docs/memory.md`](../../docs/memory.md) — three-layer memory model.
- [`docs/adapters.md`](../../docs/adapters.md) — writing your own `KnowledgeStore`.

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