tyche-memory 0.1.0

Tyche — the Memory OS for AI agents. Governed, observable memory: see tokens saved, latency, and groundedness on every call.

Tyche 🧠 — the Memory OS for AI agents

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.

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

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)

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.

See everything: the dashboard

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.

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 · original design sketch: docs/design/

Roadmap

• Repo foundation, CI
• Core store: SQLite + sqlite-vec, local embeddings, episodic write-through
• Metrics envelope (rich terminal output)
• Context optimizer with token budget
• Async governance: fact extraction, conflict detection, bi-temporal versioning, commit ledger
• Groundedness evaluator + confidence feedback loop
• Live dashboard (tyche dashboard)
• LangGraph BaseStore + LangChain integrations
• 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; the test suite runs fully offline (no API key needed).

License

MIT