Metadata-Version: 2.5
Name: openaugi
Version: 0.2.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: openai>=1.0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: tiktoken>=0.7
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'
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: ollama
Requires-Dist: httpx>=0.27; extra == 'ollama'
Provides-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

# 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](docs/reference/GETTING_STARTED.md#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](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, 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](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 [clustering-findings](docs/plans/clustering-findings.md)).

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.

---

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