andrii-su/organon

local-first semantic filesystem layer for AI agents — stable identity, lifecycle, relationships, and semantic search over MCP
Why •
Install •
Quick Start •
MCP •
How It Works •
CLI •
Agent guide
______________________________________________________________________
When an agent edits your code, it usually starts blind: grep, open a few files, guess what's related, hope nothing else breaks. Organon gives it a memory of the filesystem instead — every file is a **living entity** with a stable identity, a lifecycle, a relationship graph, change history, and a semantic index. The agent asks Organon for context *before* it touches anything.
Everything runs **100% locally** — SQLite for the graph, LanceDB for vectors, fastembed for embeddings. No accounts, no telemetry, no network in the critical path.
Why
Agent without Organon
- Reads files blindly, one grep at a time
- No idea what *depends on* auth.rs
- Can't tell a hot file from one dead for 6 months
- Re-reads the whole tree every session
Agent with Organon
- Asks for **impact** before changing a file
- Gets a **ranked context pack** for the task
- Sees **lifecycle**: active / dormant / archived
- Queries a persistent graph, not the raw tree
**Same repo. The agent just stops guessing.**
> [!IMPORTANT]
> The entity graph (identity, lifecycle, history, FTS) is built by organon watch.
> The **relationship graph and semantic vectors** are built by the Python indexer
> (organon index) — watch starts it automatically unless you pass --no-index.
> graph, impact, and semantic search are empty until indexing has run.
Install
Requires **Rust stable**, **Python 3.12+**, and uv.
Or build manually:
Prebuilt binaries for macOS and Linux are attached to each
GitHub Release (the graph,
lifecycle, history, and impact tools run from the binary alone; semantic vector
search needs the Python layer).
The first semantic index downloads the embedding model (BAAI/bge-small-en-v1.5, ~130 MB) once, then runs fully offline.
Docker
A self-contained image (Rust binary + Python layer) is published to
ghcr.io/andrii-su/organon:
Mount your project at /workspace and a named volume at /data (graph DB,
vectors, model cache).
Quick Start
What You Get
| | What |
|---|---|
| organon **CLI** | 20+ subcommands: watch, search, graph, impact, context, plan, health, doctor |
| **MCP Server** | 13 Rust-native tools over stdio or HTTP/SSE for any MCP client |
| **Entity graph** | Stable UUID per file, lifecycle, history, duplicates — in SQLite |
| **Semantic retrieval** | Local vector + FTS + hybrid search via fastembed & LanceDB |
| **Relationship graph** | Imports/references, reverse dependencies, impact analysis |
| **Agent helpers** | context packs, plan scaffolds, related-tests discovery |
How It Works
1. **Watch** — notify turns filesystem events into entity create/modify/delete/rename.
1. **Identify** — each file gets a stable UUID, content hash, size, timestamps, and git author.
1. **Classify** — the lifecycle engine assigns Born → Active → Dormant → Archived → Dead from access/modify patterns.
1. **Index** — the Python layer extracts text (code, text, PDF), embeds it into LanceDB, and parses imports into the relationship graph.
1. **Serve** — the Rust MCP server answers agent queries directly from SQLite + LanceDB.
Every entity carries its lifecycle and relationships, so agents never treat a 6-month-dormant file the same as one edited this morning.