OpenAugi

Your augmented knowledge base for Agentic work.

Human Context for Agents

You've become the bottleneck.

Your notes are scattered. Your AI can't reach them. Every conversation starts from zero.

Claude and ChatGPT memory keep you stuck in a weird bubble.

You've built years of thinking in Obsidian, Google, ChatGPT — ideas, decisions, threads you've followed and dropped. But when you talk to your agent, none of that context exists. You repeat yourself. You lose threads. The AI that's supposed to help you think doesn't know what you've been thinking about.

OpenAugi fixes this. It turns your personal data vault turned into a knowledge graph that agents can search, traverse, and understand — semantically, by keyword, by tag, by time. One SQLite file. One MCP server. Everything stays on your machine.

Status: Alpha. pip install openaugi and go. Evolving — expect rough edges. Apache-2.0 licensed.

Quick Start

pip install openaugi

# Configure and run
openaugi init    # one-time: vault path, embedding model, API key
openaugi up      # sync vault + start MCP server + watch for changes

Then register with Claude and start asking questions about your notes.

What It Actually Does

Obsidian Vault --> split --> extract --> embed --> SQLite --> MCP Server --> Claude
                     ^                                                        |
                     └------- derived views written back to your vault <-----┘

Ingest: Splits your vault by headings, extracts tags and links, builds a graph of blocks and links in SQLite. Embeds everything for semantic search. Watches for changes and re-ingests automatically.

Query: Claude gets MCP tools to search (semantic + keyword), traverse your knowledge graph, fetch full context, and understand how your ideas connect. Writes are scoped to an OpenAugi/ folder in your vault — your own notes are never touched.

One command:

openaugi up     ← ingest + file watcher + zzz dispatch + task agent + MCP server

ZZZ dispatch: Write zzz: <instruction> anywhere in your notes — any capitalization works (zzz, ZZZ, Zzz). The file watcher detects changes, ingests the block, and writes a task file to OpenAugi/Tasks/. The task watcher picks it up and launches a Claude Code agent in a named tmux session. Attach any time with tmux attach -t <task_id>. The agent's behavior is governed by a skill file you edit in Obsidian. See Getting Started.

Review pass (write-back): The loop that keeps the knowledge base maintained. On trigger ("run the review pass"), an agent routes new blocks to your area/project notes as graph links, regenerates derived view notes under OpenAugi/Views/ — a where-did-I-leave-off head per area/project plus a Dashboard — and nominates structure changes (new tags, new notes) for your approval. Agents never edit your notes; views are regenerable caches. See Review Pass.

Capture grammar — three tokens: qqq on its own line splits blocks · zzz: dispatches a task immediately (file watcher acts at ingest) · aaa: is a filing instruction that stays inert in the block until the next review pass reads it. Nothing else to learn.

Why This Exists

Most "AI + notes" tools are cloud services that want your data. Or they're RAG demos that chunk your files and call it a day.

OpenAugi is different:

• Your data stays yours. One SQLite file on your machine. No cloud. No account.
• Graph, not chunks. Tags, links, and documents are first-class nodes. Claude can follow connections, not just match keywords.
• Time-aware. Your notes have history. OpenAugi preserves it — recently created, hub velocity, threads you dropped.
• Composable. MCP tools that Claude calls directly. No middle layer, no wrapper app.

This started as a personal tool to make Claude useful with a large Obsidian vault. It works well enough that it might be useful to others.

Values

• Privacy as foundation — your data stays on your machine
• Open by default — Apache-2.0 licensed, all code public
• Augment, stay human — amplify your thinking, don't replace it
• Composable ecosystem — building blocks that work together

Data Model: Give Agents a Map

Most agent systems do brute-force retrieval — semantic search that stuffs the context window with raw documents. That's a magnifying glass in a warehouse. Agents need a map.

OpenAugi's data model is two tables — blocks and links:

• Blocks — raw content (documents, entries, tags) with deterministic identity and optional augi_tags from agent classification (same taxonomy as your own tags, stored DB-side only)
• Links — typed edges (contains, groups, links_to, routed_to) that let agents traverse connections they wouldn't find through search alone

Classification is tags; membership is links. Tags say what kind of thing a block is (one closed taxonomy, whether you or the agent applied it). routed_to links say which area/project threads a block belongs to — a block can belong to many, or none.

Five retrieval modes — semantic, keyword, graph traversal, time-based, direct lookup — all operating on the same graph.

Read the full data model | Based on Context Engineering is Index Design

Read the guide to agentic knowledge bases

Clustering & Cluster Weather

Where this sits in the pipeline: ingest and embedding happen automatically (openaugi up / the file watcher embed every block as it lands). Clustering is offline and on-demand — it never runs during ingest, so a fresh database has no clusters until you run it:

openaugi cluster --dry-run    # tune params, no writes
openaugi cluster              # write context_block:cluster nodes + a run snapshot to DB
openaugi cluster-weather      # growth/death report vs the previous snapshot (--json for agents)

Configured as named passes in ~/.openaugi/config.toml. Both shipped passes are document-level k-means (each document mean-pooled to one vector — long transcripts get one vote, not 150): a coarse pass (dims=96, k=10) surfaces life areas, and a concepts pass (dims=1536, k=8 within each area) surfaces the recurring ideas inside them. Block-level HDBSCAN was tested and retired — long documents dominate density and everything else becomes noise (see clustering-findings).

Every committed run also records a snapshot (cluster membership per pass), and openaugi cluster-weather diffs the latest snapshot against one a window ago — which clusters grew, shrank, were born, or died, plus recent writing activity per cluster. This feeds the cluster-weather lens: say "apply lens cluster-weather" and the agent turns the report into Dashboard nominations ("AI distillation service grew +8 notes in 14d — distill it into a note?").

Cluster assignments land in each data_block's metadata (cluster_assignments.{pass_id}), making them queryable and renderable without joins. See Clustering for config, the weather data model, SQL queries, and param tuning.

Documentation

• User Guide — day-to-day manual: entry points, the capture-to-view loop, trust rules, triggering a pass, the lens system in brief
• Getting Started — full install guide, CLI reference, MCP tools, Claude registration
• Architecture — data model, processing layers, module map, design decisions
• Data Model — philosophy, block kinds, navigation pattern, four-layer architecture
• Clustering — clustering + cluster weather: config format, data model, snapshots & diffs, SQL queries, param tuning
• MCP Server — tool reference and tuning
• Review Pass — the write-back loop: routing, capture grammar (qqq/zzz:/aaa:), derived views, Dashboard nominations
• Task Dispatch — optional Obsidian → tmux dispatch: write a task, watcher launches a Claude Code agent in a named session
• Remote Access — Cloudflare Tunnel setup for Claude mobile

Development

.venv/bin/pip install -e ".[dev]"
./scripts/check.sh          # lint + types + tests

See ARCHITECTURE.md for the full system map.

Contract fixtures

Three text/file contracts couple this repo to OpenAugi Mobile and are enforced only by lenient parsers: the Dashboard nomination grammar, the context-pack.json shape, and mobile's capture daily-note anchors. The golden fixtures live in tests/fixtures/contracts/ and are the shared source of truth — the mobile repo vendors copies of them. tests/test_contract_fixtures.py pins openaugi's side.

When a contract changes: regenerate the context-pack sample with .venv/bin/python scripts/gen_contract_fixtures.py (it runs the real builder over tests/contract_corpus.py; the two Markdown fixtures are hand-edited), run pytest, then in the mobile repo run scripts/sync-contract-fixtures.sh and its npm test. Both suites must pass before either repo ships — a green fixture on one side and a stale copy on the other is the drift these tests exist to catch.

License

Apache-2.0