Metadata-Version: 2.4
Name: tyche-memory
Version: 0.1.0
Summary: Tyche — the Memory OS for AI agents. Governed, observable memory: see tokens saved, latency, and groundedness on every call.
Project-URL: Homepage, https://github.com/kanishk083/tyche-memory
Author: Kanishk Wagh
License: MIT License
        
        Copyright (c) 2026 Kanishk Wagh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,langchain,langgraph,llm,memory,rag
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Requires-Dist: fastapi>=0.139.0
Requires-Dist: fastembed>=0.8.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: uvicorn>=0.51.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Requires-Dist: langgraph>=0.2; extra == 'langchain'
Description-Content-Type: text/markdown

# Tyche 🧠 — the Memory OS for AI agents

[![CI](https://github.com/kanishk083/tyche-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/kanishk083/tyche-memory/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)

> **Memory you can see and trust.** Give your LangChain / LangGraph agents long-term memory in one line — and get tokens saved, latency, and hallucination checks reported on every single call.

![Tyche dashboard](docs/assets/dashboard.png)

## Why Tyche?

Most agent memory libraries are a black box: you `add()` and `search()` and hope for the best. Tyche is built around two ideas the others skip:

1. **Observability first.** Every memory call returns metrics — latency, tokens injected, tokens saved vs. stuffing full history, which memories were used, and whether the answer was grounded in them. In your terminal *and* on a live dashboard (`tyche dashboard`).
2. **Governed writes.** Facts don't just pile up. A background governance pipeline validates sources, detects conflicts ("I live in Delhi" → "I moved to Mumbai"), versions every fact with validity intervals, and keeps a rollback-able commit ledger — like `git log` for your agent's brain.

And it's **free by default**: local embeddings (no API key), a single SQLite file for storage, zero infrastructure.

## Quickstart

```python
from tyche import Memory

memory = Memory()                                # zero config: local embeddings + SQLite
memory.add("User prefers dark mode", user_id="bhavesh")
ctx = memory.get_context("what are my UI preferences?", user_id="bhavesh")
print(ctx.text)          # optimized context, ready for your prompt
print(ctx.metrics)       # latency_ms, tokens, tokens_saved, memories_used
```

> ⚠️ **Status: early development.** Building in public — follow along! API will stabilize at v0.1 on PyPI.

## Plug into a LangGraph agent (4 lines)

```python
from langchain.agents import create_agent
from tyche import Memory, GovernanceWorker
from tyche.integrations.tools import create_memory_tools

memory = Memory(db_path="agent.db")                      # 1
tools = create_memory_tools(memory, user_id="you")       # 2
agent = create_agent(model, tools=tools, ...)            # 3
GovernanceWorker(memory).run_once()                      # 4 — background fact governance
```

The agent decides when to `remember` and `recall`; facts flow through the
governance pipeline (extraction → conflict detection → versioning). A full
LangGraph `BaseStore` implementation is also included
(`tyche.integrations.langgraph.TycheStore`). Working example:
[examples/langgraph_agent.py](examples/langgraph_agent.py).

## See everything: the dashboard

```bash
tyche dashboard --db agent.db
```

Live traces with groundedness badges, tokens-saved and latency charts, a
memory browser with version history, and the commit ledger — a git log for
your agent's brain.

## Try it in 2 minutes

| Command | What it shows |
|---|---|
| `uv run python examples/interactive.py` | hands-on playground: `/remember`, `/ask`, `/govern`, `/ledger` |
| `uv run python examples/showdown.py` | no memory vs history-stuffing vs Tyche, real API token counts |
| `uv run python examples/governance_demo.py` | "I moved to Mumbai" — conflict detection + versioned history |
| `uv run python examples/groundedness_demo.py` | hallucination flagged live + confidence feedback |
| `uv run python -m benchmarks` | the reproducible benchmark below |

## Benchmark

Same agent (llama-3.3-70b), same 12 questions over a 3-session / 20-day history
with fact updates and absent-fact trap questions. Token counts are as reported
by the provider API. Reproduce with `uv run python -m benchmarks`.

| Strategy | Accuracy | Stale answers | Hallucinations | Avg prompt tokens |
|---|---|---|---|---|
| no memory | 3/12 (25%) | 0 | 0 | 78 |
| stuff full history | 12/12 (100%) | 0 | 0 | 342 |
| **Tyche** | **12/12 (100%)** | **0** | **0** | **138** |

Stuffing grows linearly with history; Tyche stays flat. At a month of real
usage the token gap is 90%+, and governed conflict resolution keeps updated
facts (new job, new city) from fighting stale ones in the prompt.

## Architecture

Tyche is a CQRS design: a fast, **LLM-free synchronous read path** (~7 ms) and an
**asynchronous governance write path** where all the expensive intelligence lives.
If the governance worker is slow or down, agents still read memory at full speed.

```mermaid
flowchart TB
    subgraph READ["READ PATH — synchronous, LLM-free, ~7 ms"]
        Q["agent query"] --> EMB["embed query<br/>(fastembed, local, no API key)"]
        EMB --> VEC[("SQLite + sqlite-vec<br/>cosine KNN + namespace filter")]
        VEC --> OPT["Context Optimizer<br/>relevance gate → MMR dedup → token budget"]
        OPT --> CTX["prompt-ready context<br/>+ metrics: latency, tokens saved, trace_id"]
    end

    CTX --> AGENT["🤖 AI agent"]
    AGENT --> TURN["conversation turn"]

    subgraph WRITE["WRITE PATH — asynchronous governance"]
        TURN --> EPI["episodic write-through<br/>(instantly retrievable — no consistency gap)"]
        TURN --> OUTBOX[("outbox queue")]
        OUTBOX --> GOV["governance worker (LLM)<br/>extract atomic facts → duplicate / conflict verdicts"]
        GOV --> SEM["semantic facts<br/>bi-temporal versioning: superseded, never deleted"]
        GOV --> LEDGER[("commit ledger<br/>before/after diff of every write")]
        GOV --> CONS["consolidation:<br/>raw turn retires once its facts are captured"]
    end

    AGENT -.->|"answer vs retrieved context"| JUDGE["groundedness judge<br/>(sampled, off the hot path)"]
    JUDGE -.->|"confidence feedback re-ranks retrieval"| VEC
```

Key invariants (each backed by a test):

1. **Write-through** — a fact stated in turn 1 is retrievable in turn 2.
2. **No self-contradiction** — assembled context never contains both an old and a
   current version of a fact.
3. **Nothing is deleted by governance** — conflicts close a validity window
   (`valid_to`, `superseded_by`) and are reversible via the ledger.
4. **The hot path never calls an LLM** — retrieval stays fast, free, deterministic.

Deep dive: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) · original design sketch:
[docs/design/](docs/design/)

## Roadmap

- [x] Repo foundation, CI
- [x] Core store: SQLite + sqlite-vec, local embeddings, episodic write-through
- [x] Metrics envelope (rich terminal output)
- [x] Context optimizer with token budget
- [x] Async governance: fact extraction, conflict detection, bi-temporal versioning, commit ledger
- [x] Groundedness evaluator + confidence feedback loop
- [x] Live dashboard (`tyche dashboard`)
- [x] LangGraph `BaseStore` + LangChain integrations
- [x] Benchmarks vs. no-memory / history-stuffing (`python -m benchmarks`)
- [ ] Document ingestion (`memory.ingest()`) — governed knowledge with provenance
- [ ] v0.1 on PyPI

## Contributing

Early days — perfect time to get involved. See [CONTRIBUTING.md](CONTRIBUTING.md);
the test suite runs fully offline (no API key needed).

## License

MIT
