Metadata-Version: 2.5
Name: openaugi
Version: 0.4.1
Summary: Self-hostable personal intelligence engine. One pip install. One SQLite file. One MCP server.
Project-URL: Homepage, https://github.com/bitsofchris/openaugi
Project-URL: Repository, https://github.com/bitsofchris/openaugi
Project-URL: Issues, https://github.com/bitsofchris/openaugi/issues
Author-email: Chris <chris@openaugi.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: knowledge-graph,mcp,obsidian,personal-knowledge,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Requires-Dist: tiktoken>=0.7; extra == 'all'
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: local
Requires-Dist: sentence-transformers>=3.0; extra == 'local'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Requires-Dist: tiktoken>=0.7; extra == 'openai'
Provides-Extra: remote
Requires-Dist: cryptography>=42; extra == 'remote'
Requires-Dist: httpx>=0.27; extra == 'remote'
Requires-Dist: pyjwt>=2.8; extra == 'remote'
Description-Content-Type: text/markdown

# 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.](LICENSE)

---

## Quick Start

```bash
pip install openaugi              # keyword + link search, nothing leaves your machine
# optional semantic search:  pip install "openaugi[local]"  or  "openaugi[openai]"

# Configure and run
openaugi init    # 3 questions: vault, search mode, Light or Full
openaugi ingest  # index the vault (re-run any time)
openaugi kb get-context --query "what did I decide about pricing"
```

### Light or Full — same tools, different footprint

|  | 🪶 **Light** (default) | ⚡ **Full** |
|---|---|---|
| How agents reach your notes | `openaugi kb <tool>` — a shell call that answers in JSON and exits | `openaugi serve`, an MCP server ([register with Claude](docs/reference/GETTING_STARTED.md#register-with-claude)) |
| Index freshness | you run `openaugi ingest` | `openaugi up` watches the vault |
| `zzz:` tasks | wait until you launch one (`openaugi tasks run`) | `openaugi up` launches an agent for each |
| Runs in the background | nothing | `openaugi up`, plus one `serve` per client |

Every MCP tool is an `openaugi kb` command with the same arguments and the same
JSON answer — the commands are generated from the server's own tool registry,
so the two can't drift. In a Light install, add one line to your agent's
instructions (`init` prints it): *run `openaugi kb --help`, start research with
`openaugi kb get-context`*.

**CLI-only install** — for a machine where you want no server and no
background process (a work laptop, say):

```bash
uv tool install openaugi                          # or: pipx install openaugi
openaugi init --search none --mode light          # keyword search, nothing leaves the machine
openaugi ingest                                   # re-run when you want the index fresh
openaugi kb get-context --query "roadmap"         # what your agent will run
```

Nothing is registered with Claude and nothing stays running: each `openaugi kb`
call is a short process that answers in JSON and exits. Your agent's writes
land only under `<vault>/OpenAugi/`.

### Full: two processes, and why

|  | What it is | How many |
|---|---|---|
| **`openaugi up`** | the background service: ingest, watch the vault, dispatch `zzz:` tasks | **one per vault** |
| **`openaugi serve`** | the MCP interface your clients talk to | **one per client** |

They are separate because they need opposite cardinality. Two watchers see the
same `zzz:` land and both dispatch it, so one instruction becomes two agents
racing over one database — `up` therefore takes a lock and refuses to start
twice. A stdio MCP server is the other way round: Claude Desktop, Codex, and
any other client each spawn their own, so `serve` takes no lock and any number
can run.

If you have exactly one client and want a single terminal, `openaugi up
--serve` does both. Anything supervised — launchd, systemd, a container —
wants them apart.

---

## 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 (via `openaugi serve`) 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.

**The two processes:**

```
openaugi up      ← ingest + file watcher + zzz dispatch + task agent   (one per vault)
openaugi serve   ← MCP tools for your client                          (one per client)
```

**ZZZ dispatch:** Write `zzz: <instruction>` anywhere in your notes — any capitalization works (`zzz`, `ZZZ`, `Zzz`). A `zzz:` line inside a fenced code block is documentation, not a directive — that is how you write a command down without firing it. 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](docs/reference/GETTING_STARTED.md).

**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, refreshes each container's recap, and proposes structure changes (new notes, merges, registrations) for your approval. Agents never edit your notes; views are regenerable caches. See [Review Pass](docs/reference/review-pass.md).

**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](docs/reference/data-model.md)** | Based on [Context Engineering is Index Design](https://bitsofchris.com/p/context-engineering-is-index-design)

**[Read the guide to agentic knowledge bases](https://bitsofchris.com/p/how-to-build-your-agentic-knowledge)**

---

## 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:

```bash
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 `docs/plans/clustering-findings.md` (removed; in git history)).

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](docs/reference/clustering.md)** for config, the weather data model, SQL queries, and param tuning.

---

## augi-ui: the pane in Claude Code

A pane beside your agent chat: anchor on a project from your board, choose
what the chat reads, run a lens, and keep an Agent Log per project. It works
on any folder of markdown notes; with OpenAugi running, chats can search them.

```
/plugin install augi-ui --marketplace bitsofchris/openaugi
```

Then type `/augi`. Details: [docs/reference/augi-ui.md](docs/reference/augi-ui.md).

## Documentation

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

---

## Development

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

See [ARCHITECTURE.md](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/`](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
