Metadata-Version: 2.4
Name: talamus
Version: 1.0.0
Summary: Local-first knowledge compiler with graph-first retrieval for AI agents.
Author: Talamus Contributors
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: docling
Requires-Dist: docling>=2.0; extra == "docling"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Provides-Extra: bench
Requires-Dist: tiktoken>=0.7; extra == "bench"
Requires-Dist: rank-bm25>=0.2; extra == "bench"
Requires-Dist: faiss-cpu>=1.8; extra == "bench"
Requires-Dist: sentence-transformers>=3.0; extra == "bench"
Requires-Dist: mem0ai>=0.1; extra == "bench"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9; extra == "docs"
Provides-Extra: ui
Requires-Dist: fastapi>=0.110; extra == "ui"
Requires-Dist: uvicorn>=0.29; extra == "ui"
Requires-Dist: pywebview>=5.0; extra == "ui"
Provides-Extra: pdf
Requires-Dist: pypdf>=4; extra == "pdf"
Dynamic: license-file

# Talamus

[![CI](https://github.com/GCrapuzzi/Talamus-Wiki/actions/workflows/ci.yml/badge.svg)](https://github.com/GCrapuzzi/Talamus-Wiki/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-Apache--2.0-blue) ![python](https://img.shields.io/badge/python-3.11%2B-blue)

**Local-first memory with time, meaning, and verifiability — for your second brain and your AI agents.**

Talamus compiles your sources (documents, notes, and agent work sessions) into
**source-grounded, cross-linked concept notes**, builds a typed **graph as an
index**, and answers questions **with citations** — all on your machine, on the
LLM engine you already use.

<!-- demo GIF goes here: talamus demo → search → read -->

> Markdown notes you can edit in Obsidian · a graph that routes retrieval ·
> provenance on every claim · usable from the CLI, the SDK, and MCP.

## Why Talamus

Most "AI memory" is either a pile of vector chunks (no structure, no provenance)
or a cloud service (your knowledge leaves your machine). Talamus is built on three
properties that, **together**, nothing else gives you:

- **TIME** — a bitemporal model: contradictions *invalidate* old facts instead of
  deleting them — `talamus timeline`, `ask --as-of 2026-01`. *(shipped: transaction
  history + valid-time claim overlay)*
- **MEANING** — a typed, **self-emerging ontology**: free-form relation surfaces
  the fixed types can't explain are induced into *candidate types*, reviewed,
  promoted, versioned — and measurably improve retrieval (`talamus ontology`).
  *(shipped: fixed types + Ontology Lab; experimental: emergent schema at scale)*
- **VERIFIABILITY** — every note keeps its **sources**; verify single notes or in
  batch, with proposed corrections going through a review queue (`talamus verify
  --all`). *(shipped)*

Plus a wedge the others don't optimize for: **memory for agents** that need
current, cited, reasoned truth.

## Talamus vs the alternatives

|                                   | Plain RAG | llm_wiki            | Zep / mem0 | **Talamus**       |
| --------------------------------- | --------- | ------------------- | ---------- | ----------------- |
| Local-first                       | varies    | ✅                  | ❌ cloud   | ✅                |
| Human-editable notes (Obsidian)   | ❌        | ✅                  | ❌         | ✅                |
| Typed ontology for reasoning      | ❌        | ❌ statistical graph | partial    | ✅                |
| Keeps history / "truth at time T" | ❌        | ❌ overwrites        | partial    | ✅ *(MVP)*        |
| Provenance + correct-from-source  | ❌        | tracking only       | partial    | ✅                |
| Agent memory (read + write, MCP)  | ❌        | partial             | ✅         | ✅                |

## Quickstart

```bash
pipx install talamus            # or: pip install talamus

talamus demo                    # try a small example brain instantly (no LLM)
talamus search "embedding"

talamus init                    # your own brain (auto-detects your LLM engine)
talamus ingest report.pdf       # PDF / DOCX / HTML / Markdown / URL -> linked concept-notes
talamus import-vault ~/vault    # coming from Obsidian/Notion? 1:1 import, zero LLM cost
talamus ask "how does X work?"  # cited answer
talamus ui                      # optional web workbench (pip install talamus[ui])
```

Run `talamus` with no arguments for a status panel, or follow the
**[10-minute quickstart](docs/quickstart.md)**.

## Choose your engine

Talamus runs on what you already have — set it in `talamus.json` or `TALAMUS_LLM_PROVIDER`:

- `claude-cli` — your Claude subscription (default if `claude` is on PATH)
- `codex-cli` — your ChatGPT subscription (Codex is bundled with it)
- `gemini-cli` — your Gemini subscription
- `opencode` — opencode, with whatever providers you configured in it
- `antigravity-cli` — Google Antigravity (`agy`)
- `ollama` — a local model, fully offline (`TALAMUS_LLM_MODEL=llama3`)
- `anthropic-api` — the Anthropic API (`ANTHROPIC_API_KEY`)

Every engine gets per-task **model+effort tiering** automatically: bulk work
(extraction, routing) runs on the cheap tier, the answer you read on the strong
one — top quality while burning as little of your subscription as possible.

## For agents (MCP)

```bash
talamus mcp install             # writes .mcp.json for Claude Code / Cursor / Desktop
talamus hook                    # prints a SessionEnd hook to auto-capture your work
```

Agents `search` / `read_note` / `recall` / `overview` / `neighbors` to read the brain,
and `remember` to grow it. The graph is an **index, not the answer** — agents read the
real notes and cite them.

## Browse it like a wiki

Open `notes/` as an Obsidian vault: notes cross-link with `[[wikilinks]]`, so you
navigate the knowledge by hovering and clicking. Prefer a dedicated app?
**`talamus ui`** — the local web workbench (`pip install talamus[ui]`) — gives you
chat, search, clickable wikilinks, graph navigation, and domain browsing.

## How it works

Sources (Markdown, text, **PDF, DOCX, HTML, URLs**) are normalized and preserved; an
LLM extracts atomic **concept notes** (with sources, typed relations, and wikilinks);
Talamus builds rebuildable indexes (graph + BM25 + ontology) and a hierarchical
**domain overview**. Retrieval routes through the overview, then **reranks** a union of
graph + BM25 candidates, and fits the context to a **token budget** so answer cost stays
flat as the brain grows. Answers cite the notes they used, and `talamus eval` measures
retrieval quality (recall@k / MRR) so changes are judged by numbers, not vibes.

Storage is **hybrid**: `notes/*.md` is the human-editable view (Obsidian-compatible),
`.talamus/cache/` holds the machine truth (provenance) and the derived indexes;
`talamus reindex` folds your hand-edits back in. The core is **Python stdlib-only**;
extras (MCP, engines) are optional. See **[architecture](docs/architecture.md)**.

## How it compares (measured)

A real head-to-head against a dense vector-DB RAG pipeline (sentence-transformers
+ FAISS) and vanilla BM25, same corpus/queries/judgments
([details](dev/research/2026-06-rs5-competitive-shootout.md)):

| corpus | metric | Talamus | BM25 | Vector DB |
|---|---|---|---|---|
| BEIR SciFact (English, dense's turf) | recall@10 | 0.776 | 0.776 | 0.783 |
| BEIR SciFact | hit@10 | 0.793 | 0.797 | 0.793 |
| Cross-language + vague (our turf) | recall@10 | **0.886** | 0.771 | 0.700 |
| Cross-language + vague | hit@10 | **0.971** | 0.829 | 0.743 |

**On the vector DB's home turf we tie it — with zero embedding infrastructure.
On cross-language and vague queries we win decisively** (the dense model lands
last). Plus time, meaning and verifiability (100% of notes source-resolvable;
97.7% fewer tokens than loading the brain) — moats no vector DB has.

## Use cases

- **Second brain** — compile your reading and notes into a connected, cited wiki.
- **Agent memory** — give your agents a local, structured, verifiable memory they
  can both read and grow.

## Status & roadmap

**Shipped** (tested, gate-green): the sources → notes → cited-answers loop;
**multi-brain** with a federated read index (`brains`, `--all-brains`); **repo scan**
with dry-run, secret redaction and resumable jobs (`scan`, `jobs`); **persistent
indexes** (sqlite/FTS5 — search p95 at 10.000 notes: **34 ms**); the **Ontology Lab**
(emergent relation types: induce → review → promote, with measured retrieval lift);
the **temporal model** (`timeline`, `ask --as-of`); **batch verification** with a
review queue; multi-format ingestion (PDF/DOCX/HTML/URL); the CLI dashboard; the
**MCP server** (read+write with explicit scopes); the **UI workbench** (11 views,
`talamus ui [--web]`).

**Experimental**: emergent-schema quality at large scale (metrics built-in:
`ontology eval`/`stability`); UI runtime polish (smoke-tested headless, verify
rendering with `talamus ui`).

**Roadmap** ([details](dev/STATE.md)): OCR &
more formats (PPTX/XLSX/EPUB/media), packaged installers, remote
authenticated MCP, synonym-merge for emergent types, graph canvas view.

## Development

```bash
pip install -e ".[dev,mcp]"
python dev.py                    # lint + types + tests
```

## License

Apache-2.0.
