Oneiron

Long-context AI memory for agents, built around a local Rust vault.

Agent quickstart: install, connect, remember

From this checkout on a Linux/macOS development host:

python3 examples/agent-quickstart/quickstart.py --keep-running

Installs the engine, starts a fresh authenticated vault, saves and recalls an agent-private memory over HTTP, and connects MCP. No account, API key, model, or manual pairing. Needs Python 3.11+, curl 7.76+, and Rust/native build tools. It prints the URL, stop command, and ready MCP config with absolute paths for Claude Code, Codex, or OpenCode. See setup and repair and the complete example.

Why

Agents need useful memory across sessions, not just a longer prompt. They also need to know where a memory came from and which changes are allowed. Oneiron brings storage, retrieval, provenance, and write policy into one engine that applications can embed or run as a daemon.

What works today

• Local storage. Each vault uses one LMDB environment. BatchBuilder can write entities, indexes, and edges in one atomic transaction.
• Hybrid retrieval. Vector and BM25F text search, graph expansion, time filters, and phonetic matching share a query pipeline. It ranks their candidate union with configurable memory metadata.
• Typed memory and guarded writes. Claims carry provenance and lifecycle state. Actor-write APIs check configured policy and consent before admitting claim changes. Policy decisions and scoped reads expose receipts.
• A server and replication layer. oneiron-server exposes HTTP and WebSocket interfaces, including MCP over HTTP. The optional sync feature adds Loro-based replication.
• Host-bound agent components. Dreamer consolidation, durable work, typed judgments, and optional JavaScript code execution have Rust implementations. Hosts supply the required inference, scheduling, policy, and budget bindings. Standard daemon startup does not bind a Dreamer model or code executor.
• Models behind one seam. Generative models plug in through the LlmBackend trait. Adapter crates cover a local in-process runtime, OpenAI-compatible and Anthropic Messages APIs, Gemini, and a self-hosted model server. Typed decisions use a separate seat, RemoteDecisionSeat; the System One adapter implements it. The host loads the model or holds the credentials; no adapter bundles model weights. Standard daemon startup binds no generative model.
• Optional embedding backends. The daemon can run with no embedder, provision a local embedder, or use a configured endpoint.
• Owner actions. The CLI covers where the vault lives (doctor), backups, restore rehearsal, restore, export, the secret-scan switch, and one-act approval of an import batch or an agent run. A running server offers the same actions under /v1/owner, except two: restore is CLI-only, and export is POST /v1/core/facade/vault.export. None of them needs a model. See docs/ops/owner-actions.md.
• Agents over MCP. oneiron mcp connects Claude Code and Codex to a running vault over stdio, with a scoped, revocable agent credential from oneiron token agent. See docs/ops/connect-an-agent.md.

These are implemented APIs and components. Oneiron is pre-release.

Quick Start: the embedded Rust API

This stores and reads a byte payload. It needs no model, embedding, or network service. It is a low-level storage example, not a typed claim or a retrieval query.

use oneiron::registry::ENTITY_TYPE_SUMMARY;
use oneiron::{EntityId, TimeRange, Vault, VaultConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let vault = Vault::open("./my-vault", VaultConfig::device())?;

    let id = EntityId::now();
    let payload = b"Hello, Oneiron!";
    let timestamp = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)?
        .as_secs();
    vault.put_entity(
        &id,
        ENTITY_TYPE_SUMMARY,
        TimeRange {
            start: timestamp,
            end: timestamp,
        },
        timestamp,
        payload,
    )?;
    assert_eq!(vault.get(&id)?.as_deref(), Some(payload.as_slice()));
    println!("Stored and read entity {}", id.to_ulid());
    Ok(())
}

Vault::open can create a vault. On Linux, Vault::open_existing opens only an initialized vault and never creates one.

Manual installation from source

The agent quickstart installs and connects in one run. To install only the CLI, use the Rust toolchain pinned in rust-toolchain.toml, from the repository root:

cargo install --locked --path crates/oneiron-server --bin oneiron

This installs oneiron in Cargo's bin directory. Without --bin oneiron, the package also installs oneiron-server (the same CLI) and oneiron-broker. Oneiron is pre-release; this path uses source builds rather than assuming a published package or release binary. For the exact noninteractive init, agent credential, serve and first-memory calls, see agent setup. See DEPLOYMENT.md for service templates.

Building from source

The SDK's generated Rust files are not committed: the crates that include them (oneiron, oneiron-server, oneiron-remote, oneiron-napi, oneiron-uniffi, oneiron-code-check, oneiron-py) run the SDK generator (crates/oneiron-sdk-generator) inside their build scripts, once per change of the verb table (scripts/sdk/verbs/), the Rust types it names or the generator itself, into the target directory. No Python runs for this. The run key covers the generator's source, Cargo.lock, the manifests and the compiler. It does not see a local override of the generator's dependencies ([patch] to a path, paths in .cargo/config, or --config). After changing one, delete target/<profile>/sdk-generated.

An incremental build reruns those build scripts only when a file the last run depended on changes: a verb file, type_names.json, a hand-written input, a crate source file that defined an item the generator resolved, or a module file it walked (the run directory's .sdk-deps lists them), and Cargo.lock or the manifests. A body edit in any other crate file reruns nothing. The limit: a new file, or a new same-named item in a file the generator did not resolve from, is not seen by an incremental build until a watched file changes; delete target//sdk-generated to force. A clean build always regenerates, and the merge train regenerates the SDK outputs on every train top (TRAIN-REGEN).

The SDK packages make their generated files in their own builds: bun run build in packages/oneiron and bun run prepare in packages/oneiron-client (each runs the generator with cargo run), and maturin build for oneiron-py. The agent-SDK reference generated from the verb table (types.md, facade-types.md, verbs.md) is published from main at https://oneiron-dev.github.io/oneiron/agent-sdk/, and every cargo build keeps a local copy in target/debug/sdk-generated/agent-sdk/ (target/release/... for a release build).

Debug information is adjustable (details in build performance):

• Default: dev and test builds use debug = "line-tables-only", so backtraces and panics still show file and line.
• Perf work: RUSTFLAGS="-C force-frame-pointers=yes" cargo build --profile profiling builds release code with full debug information and no LTO into target/profiling.
• One run with full debug information: CARGO_PROFILE_DEV_DEBUG=full cargo test ..., or cargo test --config 'profile.dev.debug="full"' ....

Web frontend

The engine's web frontend lives in apps/web, imported with its complete Git history from oneiron-dev/oneiron-web. It includes the TanStack Start console/workbench and its existing Tauri desktop shell. The UI still uses fixtures and is not connected to an engine; moving it does not enable vault operations or change its design.

Run its Bun commands from apps/web. Its Tauri package keeps its own Cargo workspace and lockfile, separate from the engine workspace and the existing macOS menu-bar app. See the frontend README for its setup and current runtime boundaries.

Crates

This table lists selected crates, not the whole workspace. The code map has a row for each engine crate under crates/ and links to its modules and source files. It does not cover the applications under apps/.

Crate	Role
oneiron	Local vault, retrieval, typed memory, and write policy.
oneiron-server	HTTP and WebSocket daemon around the vault.
oneiron-driver	In-process agent runtime driver.
oneiron-ffi	C interface to the engine.
oneiron-napi	Native Node.js bindings.
oneiron-py	Native Python extension.
oneiron-remote	Shared embedded and remote SDK backend.
oneiron-uniffi	UniFFI binding of the SDK verb table over the shared OneironClient (embedded and remote).
oneiron-android	JNI/Kotlin ownership adapter.
oneiron-llm-anthropic	Anthropic Messages adapter.
oneiron-llm-gemini	Gemini adapter.
oneiron-llm-openai	OpenAI-compatible adapter.
oneiron-llm-own-server	User-hosted model endpoint adapter.
oneiron-llm-local	Host-supplied in-process model adapter.
oneiron-llm-systemone	Remote typed-decision service adapter.
oneiron-image-comfyui	ComfyUI image adapter.
oneiron-image-openrouter	OpenRouter image adapter.
oneiron-mesh-transport	Vault-scoped peer transport.
oneiron-linear	Linear issue-mirroring adapter.
oneiron-docedit	Native document editing and revision support.
oneiron-xlsx-formula	In-process spreadsheet formula recalculation.
oneiron-seal	PDF signature sealing and verification.
oneiron-guest	Linux sandbox guest agent and conformance adapter.
oneiron-sandbox-contract	Shared host/guest sandbox protocol rules.
oneiron-vault-contract	Supervisor-to-vault process protocol and limits.
oneiron-vm-outbox	A vault VM's root outbox companion binary.
oneiron-bench	Benchmark and evaluation harness.
oneiron-macos	macOS menu-bar voice recorder embedding the vault.

Storage layout

This diagram matches the vault's named-database manifest. It shows storage components, not which optional runtime features are enabled.

Development and documentation

The merge bar is cargo check --workspace --all-features on the head. AGENTS.md covers the build rules and PRs.

Tests use cargo-nextest. The default profile skips the slow set; the full profile includes it.

cargo nextest run --locked -p oneiron --all-features
cargo nextest run --locked -p oneiron --features sync,test-hooks --profile full

The second command runs the sync build with the slow set included.

Some integration tests reach crate-private items through oneiron::test_doors, which builds only under --cfg oneiron_test_support (never a cargo feature):

RUSTFLAGS="--cfg oneiron_test_support" cargo test --locked -p oneiron --all-features --test <file>

• oneiron.skills.md: HTTP API reference.
• docs/ops/owner-actions.md: backup, restore, export, and owner approvals.
• UPGRADING.md: authentication and text-index upgrade notes.

License

Apache-2.0.