orven

# Orven Orven is an MCP-compatible virtual context and memory system. It gives AI assistants a structured, paged view of a project so they can navigate and reason about large codebases without exhausting the context window. Orven implements the Model Context Protocol and nothing else. Any editor, assistant, or agent that speaks MCP can connect to it, and Orven neither knows nor depends on which client is calling. ## Why it exists An assistant working in a real repository has two bad options. It can read whole files, which fills the context window with code it does not need, or it can guess from filenames, which produces wrong answers. Both degrade as the project grows. Orven applies the memory model an operating system already uses for this problem. The project is parsed once into an index of symbol signatures. The assistant reads that index to orient itself, then requests the specific function or type it needs. Bodies are loaded on demand, tracked while in use, and released when they are not. Verbose material such as logs and diffs is written to disk and replaced in context by a short pointer. On Orven's own source, a full-source read of roughly 50,000 tokens becomes an index of roughly 4,700, about 90 percent smaller, while every symbol remains one call away. Run `npm run bench` to measure any project. ## How it works Orven models the context window as three tiers. | Tier | Contents | Stored in | | --- | --- | --- | | L1, active frames | Symbol bodies and traces currently in use | `.orven/frames.json` | | L2, page table | Signature index of every class, function, and type | `.orven/page-table.json` | | Swap, disk | Traces, diffs, logs, and written-back notes | `.orven/swap/` | Parsing uses tree-sitter, so the index is derived from real syntax trees rather than regular expressions or line chunking. Symbols are stored as byte ranges; bodies are re-read from source on request and never duplicated into the index. Four mechanisms keep this correct while the project changes: - **Incremental re-indexing.** Each indexed file carries an mtime and size fingerprint. Only changed files are re-parsed. A symbol requested mid-edit is re-indexed before it is read, so the returned body is always byte-exact. - **Eviction.** A background loop releases least-recently-used frames when L1 exceeds a high-water mark, down to a low-water mark. The most recently used frame and anything touched within a grace period are never evicted. - **Write-back.** Notes authored by the assistant are not re-derivable from source, so they are written to swap before their frame is released and can be read back later. - **Locking.** The MCP server and the CLI are separate processes. A cross-process advisory lock serializes every read-modify-write of the frame table. ## Requirements Node.js 22.13 or newer. No native toolchain is required; parsing uses WebAssembly grammars. ## Installation ### Run without installing ``` npx orven init ``` This is the quickest way to try Orven and needs nothing installed beyond Node.js. ### Install globally ``` npm install -g orven ``` Recommended for regular use. It puts two commands on your `PATH`: | Command | Purpose | | --- | --- | | `orven` | The command-line interface. | | `orven-mcp` | The MCP server. Started by your MCP client, not by hand. | ### Build from source ``` git clone https://github.com/naseridev/orven.git cd orven npm install npm run build ``` `npm install` builds the project automatically. The result is two executables under `dist/`: the CLI (`dist/cli/index.js`) and the MCP server (`dist/server/index.js`). Link them into your `PATH` with `npm link` if you want to use `orven` from anywhere. ## Initialization Run `init` inside the project you want indexed: ``` cd /path/to/your/project orven init ``` `init` performs four steps: 1. Creates `.orven/` and its swap directory. 2. Parses the project and writes the page table. 3. Resets the frame table. 4. Registers the MCP server in `.mcp.json` at the project root. Re-running `init` re-indexes the project. It is safe to run at any time. ## MCP integration `init` writes a standard MCP server entry to `.mcp.json` at the project root. When Orven is installed globally or built from source, the entry points straight at the server: ```json { "mcpServers": { "orven": { "command": "/path/to/node", "args": ["/path/to/orven/dist/server/index.js"], "env": { "ORVEN_ROOT": "/path/to/your/project" } } } } ``` When `init` is run through `npx`, that path would live in a temporary cache that npm is free to delete, so Orven writes a self-resolving entry instead: ```json { "mcpServers": { "orven": { "command": "npx", "args": ["-y", "--package=orven@1.0.0", "orven-mcp"], "env": { "ORVEN_ROOT": "/path/to/your/project" } } } } ``` This form contains no machine-specific paths, so it is the one to keep if `.mcp.json` is committed to a shared repository. The first connection may be slower while npm fetches the package. Re-running `init` after a global install rewrites the entry to the direct form. Clients that read `.mcp.json` from the project root pick either form up automatically. Clients that keep configuration elsewhere can be pointed at the same command, arguments, and environment. `ORVEN_ROOT` determines which project the server serves; everything else is standard MCP stdio transport. The server exposes five tools: | Tool | Purpose | | --- | --- | | `orven_get_page_table` | Return the project's signature index, without function bodies. | | `orven_page_in` | Load one symbol's full body into active context. | | `orven_inspect_swap` | Read a trace, diff, or saved note back from swap. | | `orven_free_frame` | Release a frame and reclaim its tokens. | | `orven_write_scratch` | Hold working notes in memory, written back to swap on eviction. | A typical session begins with `orven_get_page_table` to orient, followed by `orven_page_in` for each symbol actually needed. `orven_page_in` also returns the symbols most likely to be needed next, derived from the dependency graph, and the symbols that call the one being read. ## Commands ``` orven init Index this project and publish the MCP server orven status Show index, context use and efficiency orven reset Release working context and compact swap orven remove Remove Orven from this project ``` All commands accept `-C, --root <dir>` to target a directory other than the working directory. - `status` prints a short summary by default. `--verbose` adds full engine diagnostics: watermarks, dependency-graph statistics, prefetch tuning, swap composition, and lock state. - `reset` releases stale frames and compacts swap journals. `--all` releases every frame. Nothing is lost; scratch notes are written back to swap first. - `remove` deletes `.orven/` in full and removes the `orven` entry from `.mcp.json`, restoring the project to its previous state. It prompts for confirmation unless `--yes` is passed. Other entries in `.mcp.json` are preserved, and the file is deleted only if Orven was its sole entry. `purge` and `uninstall` remain as hidden aliases for `reset` and `remove`. ## Configuration Defaults are written to `.orven/config.json` on first `init` and can be edited directly. | Key | Default | Effect | | --- | --- | --- | | `l1TokenBudget` | `12000` | Target size of active context. | | `highWaterRatio` | `0.85` | Fraction of budget that triggers eviction. | | `lowWaterRatio` | `0.6` | Fraction of budget eviction reclaims down to. | | `evictionGraceMs` | `30000` | Recently used frames are protected for this long. | | `sweepIntervalMs` | `15000` | Background eviction check interval. | | `daemonEnabled` | `true` | Enables automatic eviction. | | `reindexEnabled` | `true` | Enables incremental re-indexing. | | `reindexIntervalMs` | `20000` | Background coherence check interval. | | `maxScratchBytes` | `32768` | Size limit for a single scratch note. | | `swapCompactionEnabled` | `true` | Enables swap journal pruning. | | `maxSwapBytes` | `8388608` | Swap size budget. | | `swapJournalKeep` | `24` | Journals retained before pruning by age. | | `prefetchEnabled` | `true` | Enables next-symbol prediction. | | `prefetchMaxHops` | `2` | Dependency-graph depth for prediction. | | `prefetchDecay` | `0.5` | Score decay applied per hop. | | `prefetchBudgetTokens` | `1500` | Token budget for predictions. | | `prefetchDepth` | `6` | Maximum predicted symbols per request. | | `prefetchEager` | `false` | Include predicted bodies, not just signatures. | | `prefetchAdaptive` | `true` | Adjusts prediction depth to measured accuracy. | | `purgeTargetRatio` | `0.8` | Share of active context `reset` reclaims. | | `maxFileBytes` | `1500000` | Files larger than this are skipped. | | `ignoredDirectories` | build and vendor directories | Excluded from indexing. | Environment variables: | Variable | Effect | | --- | --- | | `ORVEN_ROOT` | Project directory the MCP server serves. | | `NO_COLOR` | Disables colour output. | | `ORVEN_ASCII` | Forces ASCII glyphs for terminals without Unicode. | | `ORVEN_NO_FLAVOR` | Disables the optional flavour line in CLI output. | | `ORVEN_FLAVOR_SEED` | Makes that line deterministic, for scripted or snapshot use. | ## Common workflow ``` cd my-project orven init # index the project, register the MCP server # connect your MCP client, then work as usual orven status # check index freshness and context use orven init # re-index after significant changes orven reset # release working context if it fills up ``` In normal use the engine manages itself. Eviction, re-indexing, and swap compaction run in the background while the MCP server is connected. `status` is the command you will use most; `reset` is rarely needed manually. ## Architecture ``` src/ types.ts Shared domain model config/ Paths, defaults, thresholds util/ Atomic JSON writes, file locking, token estimation ast/ tree-sitter parsing, symbol and reference extraction memory/ Page table, frames, swap, eviction, graph, write-back server/ MCP server, tools, eviction daemon, coherence sweeper cli/ Command-line interface and rendering ``` `memory/`, `ast/`, and `server/` contain no client-specific logic. The server implements MCP and is unaware of what is connected to it. The CLI is presentation only and holds no engine state. Project state is confined to `.orven/`: ``` .orven/ config.json Settings page-table.json Symbol index frames.json Active frames meta.json Counters and timestamps swap/ Traces, diffs, written-back notes ``` `predictions.json` is added once prefetching has data, and `frames.lock` exists only while a write is in progress. Source files are never modified. ## Development The source lives at [github.com/naseridev/orven](https://github.com/naseridev/orven). Bugs and feature requests belong in the [issue tracker](https://github.com/naseridev/orven/issues). ``` npm run build Compile TypeScript npm run typecheck Type-check without emitting npm test Build, then run the CLI and engine test suites npm run bench Report index size and token reduction for a project npm run dev:cli Run the CLI from source npm run dev:server Run the MCP server from source ``` The test suite covers the CLI surface end to end and the memory engine through the MCP interface, including byte-exact paging across edits, write-back and recovery, eviction behaviour, and concurrent access from multiple processes. `web-tree-sitter` is pinned to 0.24.x. Later versions require grammar modules in a format the prebuilt grammars used here do not provide. ## License GNU General Public License v3.0. See [LICENSE](LICENSE) for the full text.