Your filesystem, finally alive
Organon is a semantic layer over your filesystem. Every file becomes a living entity — with identity, context, relationships, and a lifecycle. Built for humans and AI agents alike.
01
Why Organon exists
Files are not static blobs. They're created with intent, evolve over time, relate to other files, and eventually become irrelevant. No existing tool treats them this way.
Entity Graph
Identity for every file
Each file gets a stable identity, purpose description, tags, and a rich relationship graph — not just a path string.
Lifecycle Engine
Files as living organisms
Born → Active → Dormant → Archived → Dead. Organon tracks state transitions and surfaces what matters now.
Semantic Search
Find by meaning, not name
Vector search via fastembed + LanceDB. Full-text via SQLite FTS5. Hybrid mode combines both with metadata filters.
MCP Server
Agent-native from day one
Claude, Cursor, and any MCP-compatible agent can query, relate, and navigate your file graph directly.
Watcher
Always in sync
Filesystem events drive entity creation and updates in real time. No manual indexing, no stale data.
Portability
100% local storage
SQLite for the entity graph. LanceDB for vectors. Everything lives on disk — no cloud dependency.
02
Lifecycle state machine
Every entity moves through a deterministic state machine. Transitions are triggered by filesystem events, git activity, access patterns, and explicit user commands.
Born
File detected for the first time
Active
Recently modified or accessed
Dormant
No activity for a threshold period
Archived
Explicitly archived or auto-retired
Dead
File deleted from filesystem
03
Architecture
A Rust core for speed and correctness, a Python AI layer for embeddings and extraction, and an MCP server that connects everything to any compatible AI agent.
Layer 01
organon-core
Rust library. Filesystem watcher via notify. Entity graph in SQLite. Full-text search via SQLite FTS5. Lifecycle state machine.
Layer 02
ai/ extractor + embeddings
Python. Content extraction for text, PDF, and code. Local semantic vectors via fastembed + LanceDB.
Layer 03
organon-mcp + cli
Rust-native MCP server exposing search, graph, context, and impact tools to agents. The organon CLI for power users: watch, find, graph, diff, export.
04
CLI reference
The organon binary covers watching, finding, searching,
graphing, diffing, and exporting. Global flags: --quiet,
-v, -vv.
# Watch a directory and index changes (runs the embedder too) organon watch . # Start the MCP server for Claude Desktop, Cursor, or any MCP agent organon mcp # stdio mode organon mcp --sse # HTTP / SSE mode organon mcp --scope ./src # limit a session to a subtree # Find entities with metadata filters organon find --state active --ext rs organon find --modified-after 2026-01-01 --larger-than-mb 10 # Semantic + full-text search with filters organon search "watcher" --state active --ext rs --mode hybrid organon search "embedding model" --mode vector organon search --like src/auth.rs --limit 5 # Agent helpers — context packs, impact, change plans, tests organon context "auth refactor" --scope . --budget 8000 organon impact src/auth.rs --depth 3 organon plan "add health command" --file src/main.rs organon related-tests src/auth.rs # Graph relationships — text, DOT, or Mermaid output organon graph path/to/file.rs --depth 2 --format mermaid # Inspect, diff, export, and check health organon status path/to/file.rs organon diff . --json organon export --format json organon health organon doctor
Connect an agent with the step-by-step guides: Claude Desktop, Cursor, or the general agent usage reference.
05
Stack
Every dependency chosen for local-first, agent-native operation — nothing in the critical path requires a network call.
| Layer | Technology |
|---|---|
| Core library | Rust — notify · tokio · rusqlite (FTS5) |
| Semantic vectors | Python — fastembed · lancedb |
| Content extraction | Python — text · PDF · code |
| Agent protocol | MCP — Rust-native, Model Context Protocol |
| CLI | organon — watch · search · graph · context · plan |
| Storage | SQLite + LanceDB — 100% on-disk |
Install dependencies with uv sync (Python layer) and
cargo build --release (Rust core). See
setup.sh for full bootstrapping.