Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

rusty-brain

Local-first, persistent memory for AI coding agents — a Rust daemon with hybrid (vector + keyword + graph) retrieval over SQLite, exposed via MCP and a CLI.

Status: early development. The pieces described below are implemented and covered by unit and integration tests. A bounded historical Claude Code scorecard provided N=5 proxy evidence; the active runner is OMP-native and can select configured models. Neither is production proof: performance, scale, sustained concurrency, resource exhaustion, semantic quality beyond the supported local model's authored evaluation corpus, and multi-machine adoption remain unmeasured. Treat it as a work in progress, not a finished product. Interfaces and the on-disk format may change.

What it is

rusty-brain is a small memory substrate that an AI coding agent (or several, concurrently) can write notes to and recall from. It runs as a single local daemon backed by one SQLite database, and is reachable two ways:

  • a command-line interface (rusty-brain), and
  • an MCP server (rusty-brain mcp) that exposes memory operations as tools to any MCP-capable agent.

Memories are scoped to a namespace (global, per-project, or per-session), carry lightweight enrichment (summary, keywords, tags, type, importance), and can be linked to one another. Recall fuses full-text search, vector similarity, and graph proximity into a single ranked result set.

It is deliberately a substrate, not an orchestrator: it stores and retrieves memory for agents but has no notion of tasks, scheduling, or agent lifecycles.

Background

Before building this, we surveyed a number of existing agentic-memory systems. They informed the design — our recency/importance/relevance ranking and our treatment of consolidation and forgetting are well-trodden ideas — but their architectures did not align with our design criteria. We wanted something local-first, built from small purpose-built crates with compiler-enforced boundaries, with a single source of truth on disk and a lean default dependency footprint, rather than a large general-purpose system. rusty-brain is that focused rebuild. The principles we settled on:

  • A workspace of focused crates, never a monolith — boundaries enforced by the compiler, heavy/optional pieces behind feature flags or separate crates.
  • One database, one transaction, one source of truth — memories, full-text index, and vectors live in a single SQLite file; writes serialize through one thread, reads run concurrently over WAL.
  • Fail-closed where it matters, fail-open where it shouldn't — namespace isolation and the embedding-dimension contract refuse to run on doubt; best-effort capture hooks continue on handled errors rather than making memory a prerequisite.
  • Reproducible from git — file-discovered, checksummed migrations; CI rebuilds a fresh database from committed SQL and exercises every query path.

Architecture (high level)

flowchart TB
  subgraph clients["Clients"]
    CLI["rusty-brain CLI"]
    AGENT["MCP-capable agent"]
    HOOKS["rusty-brain-hooks<br/>(capture, fail-open)"]
  end

  AGENT -->|"JSON-RPC over stdio"| MCPSRV["rusty-brain mcp<br/>(MCP server)"]

  subgraph daemon["rusty-brain daemon (one local process)"]
    ENGINE["engine<br/>enrich → embed → store → link → recall"]
    WRITER["single writer thread"]
    POOL["read pool (WAL)"]
    BUS["change broadcast"]
  end

  CLI -->|"Unix socket"| daemon
  MCPSRV -->|"Unix socket"| daemon
  HOOKS -->|"Unix socket"| daemon

  ENGINE --> WRITER
  ENGINE --> POOL
  ENGINE --> EMB["embeddings<br/>deterministic · Voyage · local ONNX"]
  WRITER --> DB[("SQLite + sqlite-vec<br/>memories · vectors · links · FTS")]
  POOL --> DB
  WRITER --> BUS

  classDef client fill:#e3f2fd,stroke:#4781c4,color:#0d2b4e;
  classDef proc fill:#ede7f6,stroke:#7e57c2,color:#311b54;
  classDef store fill:#fff3e0,stroke:#ef8e3a,color:#5a3209;
  classDef embed fill:#e8f5e9,stroke:#52a45a,color:#1b3d20;
  classDef accent fill:#fce4ec,stroke:#c96198,color:#5a1535;
  class CLI,AGENT,HOOKS,MCPSRV client;
  class ENGINE,WRITER,POOL proc;
  class EMB embed;
  class DB store;
  class BUS accent;
  style clients fill:#f2f7fd,stroke:#9bbbe0,color:#0d2b4e;
  style daemon fill:#f6f3fb,stroke:#b9a7da,color:#311b54;
Loading

A deeper walkthrough — component boundaries, the write and recall data flows, and the namespace model — lives in docs/ARCHITECTURE.md. The memory-management policy the system enforces (taxonomy, consolidation, retrieval, degradation, health, security) is declared in docs/COGNITION.md.

What works today

Implemented and test-covered (correctness is the primary coverage; see Testing for bounded capability evidence and limits):

  • Store and recall memories scoped by namespace, with enrichment and graph links.
  • Hybrid retrieval fusing FTS5 keyword search, sqlite-vec vector similarity, and 1-hop graph expansion. Ranking is a weighted linear blend of vector/keyword/graph/ importance/recency signals by default, with an opt-in Reciprocal Rank Fusion (RRF) mode and a confidence dampener. A trust-class prior (measured CI > measured local > human-confirmed > agent-attested > inferred) reorders otherwise-identical results, and a calibrated abstention gate withholds weak matches entirely — recall returns a machine-readable abstention reason instead of the 5th-best hit.
  • Contradiction surfacing — results carry a contested flag when a memory has an active contradicts link (best-effort, never fails recall).
  • A single-writer daemon over SQLite WAL with a concurrent read pool, change notifications via an in-process broadcast, and auto-start from any client command.
  • An MCP server exposing 12 MCP tools over stdio (six advertised by default; all 12 remain directly routable).
  • A CLI for direct use and scripting.
  • Activation and operations commands: bounded project init/import, read-only status/stats plus doctor, and portable export/backup/JSON restore.
  • An optional loopback HTTP surface for non-MCP local clients, off by default and deliberately not an authentication boundary.
  • Pluggable embeddings — an offline deterministic provider (default), a Voyage API provider, and an optional local ONNX provider behind a feature flag.
  • Best-effort capture hooks (rusty-brain-hooks) and an installer (rusty-brain-install) for wiring memory capture into agent CLIs.
  • Opt-in maintenance jobs for link decay, near-duplicate consolidation, and importance recalibration. All are disabled by default. Consolidation selects a surviving memory and supersedes duplicates; it does not synthesize a merged note or adjudicate contradictions. Importance recalibration uses access/recency signals, not explicit usefulness feedback.
  • Usefulness feedback (helpful/wrong/stale) adjusts a memory's confidence; supersession keeps replaced memories out of active recall.
  • Write-path defenses — every durable write passes a per-namespace validation gate (permitted channels, types, size, anchors) before it can reach SQLite; writes carry the daemon-stamped channel tag (origin_channel: hook/mcp/cli over the UDS, http for the loopback listener — a separate column from the evidence-derived trust_class) and untrusted-origin rows are quarantined out of recall. Hook folds are source-filtered, so instruction-shaped content planted mid-session never becomes a durable memory, and commit-anchored memories report STALE (never silently reused) once the repo moves past their anchor.

On upgrade, migration 015 marks historical rows with neither source nor channel as legacy_unknown. They remain inspectable/exportable but leave recall and startup context; edits or human curation do not clear this classification. New identity-less writes remain accepted and explicitly unverified, not trusted; internal origin_source=job writes keep their existing behavior. Restart the daemon with the upgraded binaries before relying on the cutover. See the provenance recovery policy.

Planned / deferred (designed but not built): LLM-assisted memory evolution (reconciliation, reflection), a networked multi-host surface with real auth, and an ANN vector index for larger corpora. See Roadmap.

Quickstart

Install

Tagged releases ship prebuilt, checksummed tarballs for macOS (Apple Silicon and Intel) and Linux x86_64 on the releases page. Each tarball contains the three binaries (rusty-brain, rusty-brain-hooks, rusty-brain-install). One-line install (needs the gh CLI; pick your target):

TARGET=aarch64-apple-darwin   # or x86_64-apple-darwin / x86_64-unknown-linux-gnu
gh release download --repo brianluby/rusty-brain --pattern "*-${TARGET}.tar.gz" --pattern SHA256SUMS && shasum -a 256 --check --ignore-missing SHA256SUMS && mkdir -p ~/.local/bin && tar -xzf rusty-brain-*-"${TARGET}".tar.gz --strip-components=1 -C ~/.local/bin

(sha256sum on Linux; make sure ~/.local/bin is on your PATH. Optionally verify build provenance first: gh attestation verify rusty-brain-*.tar.gz --repo brianluby/rusty-brain.)

Or manually: download the tarball for your platform plus SHA256SUMS from the release, check it, and unpack the binaries somewhere on your PATH.

Or build from source:

Prerequisites

  • Rust stable (pinned via rust-toolchain.toml). SQLite is bundled (no system dependency).

Build

cargo build --release
# binaries: target/release/rusty-brain  (+ rusty-brain-hooks, rusty-brain-install)

Use the CLI

Client commands auto-start the daemon on first use (and connect to it thereafter), so you can go straight to storing and recalling:

# seed a fresh brain from existing project context (CLAUDE.md, README,
# CHANGELOG.md, docs/**/*.md, and recent decision-ish git commits)
rusty-brain init --yes

# store a deliberate decision and protect it from unattended maintenance
rusty-brain remember "We use a single-writer daemon over SQLite WAL" \
  --type architecture_decision --importance 8 --tags storage --tags concurrency --curated

# back a claim with verifiable evidence — the daemon derives the trust class
# from the evidence kind + channel (a CI claim additionally needs --commit)
rusty-brain remember "cargo test -p rb-store passes in 41s on CI #4821" \
  --type bug_fix --commit $(git rev-parse HEAD) --evidence-ci "run-4821"


# recall by free-text query (hybrid keyword + vector + graph)
rusty-brain recall "how is writing serialized?" --limit 5

# fetch, list, traverse links, see project context
rusty-brain get <id>
rusty-brain list --min-importance 6
rusty-brain graph <id> --depth 1
rusty-brain context

# adjust a memory you no longer fully trust, or mark two memories as
# contradicting (both then surface `contested: true` on reads)
rusty-brain update <id> --confidence 0.3
rusty-brain update <id> --curated    # enable unattended-maintenance protection
rusty-brain update <id> --uncurate   # explicitly remove that protection
rusty-brain link <from-id> <to-id> --type contradicts --reason "policy reversed"

# inspect a decision's full stored claim, context, provenance and typed source
# anchors alongside its bounded supersede chain and contradiction links
# (read-only: no access/confidence writes; source references remain unverified)
rusty-brain history <id>
rusty-brain history <id> --depth 3 --json

# retroactively redact secrets from every stored memory, then re-embed
rusty-brain scrub
rusty-brain reembed

# list or undo first-run/import batches
rusty-brain init --list-batches
rusty-brain init --undo <batch-id>

# export stored memories (sorted by id for git-diffability; run `scrub` first
# if legacy or manually-entered rows may still contain plaintext secrets)
rusty-brain export --format markdown
rusty-brain export --format json --min-importance 5
rusty-brain export --format csv

# one-command timestamped backup (with optional retention pruning)
rusty-brain backup
rusty-brain backup --retention 5 --format json
rusty-brain backup --list

# restore from a JSON export (idempotent via dedup, re-embeds under current model)
rusty-brain restore backup-20260702T210230.123456789.json
echo "$JSON" | rusty-brain restore -

# add --json to any command for machine-readable output
rusty-brain recall "sqlite" --json

human_curated defaults to false. It protects authored state from automatic duplicate collapse, policy review, importance/confidence maintenance and retention. Explicit deletion, review resolution and remember --supersedes <id> still work; negative feedback and secret redaction still apply. JSON export/restore preserves the marker for new rows; restoring duplicate content never overwrites an existing row's curation choice. Protection is not authorization, verified truth or a recall eligibility/ranking boost. Upgrade and restart the daemon to enforce it.

For explicit how-to records, use the existing bug_fix/code_pattern types and the qualified procedural-memory format. Failed attempts and untested proposals remain qualified advice, not validated repairs or authorization to run their steps.

context is compact navigation for current eligible decisions, constraints and preferences, not a recent-activity feed or complete policy. Previews carry full UUIDs and deliberately incomplete subjects; use get/history in the same namespace for exact stored qualifications and source handles. Context text omits access counters and relative ages; deterministic bytes do not guarantee provider prompt caching. CLI context --json and MCP structured context return { stable, snapshot, repo_state }, without full memory bodies.

This is a breaking wire v3 cutover. Upgrade CLI, daemon, MCP and hook binaries together, restart the daemon, and reinstall the owned OMP extension. Older wire versions are rejected rather than silently translated.

Initial CLI/MCP daemon connection attempts share one socket/handshake deadline: five seconds normally, or 120 seconds when resolved configuration requests a local backend/model. All attempts and backoff within one MCP reconnect share that budget; client-side capability rejection leaves healthy connections intact. Slow first-time model downloads can exceed the startup bound; run serve explicitly to prewarm them. Startup failures report the observed phase, child status when available, a redacted stderr tail and the attempt's log path. Failed-attempt logs live under the cache directory's rusty-brain/logs (0700, files 0600), retain at most 64 KiB per attempt, and prune completed logs toward an eight-file retention target without removing active attempts. The surfaced excerpt is capped at 8 KiB; the private raw files can contain secrets.

You can also run the daemon explicitly in the foreground:

rusty-brain serve            # runs until Ctrl-C

Embedding providers

By default the daemon uses an offline deterministic provider. It is reproducible and requires no network or API key, but its vectors are not semantic — they exist so the system runs and so ranking is deterministic in tests, not to give good real-world recall. For meaningful semantic recall, configure a real provider:

Provider How to select Notes
Deterministic (default) (none) Offline, non-semantic. Fallback when nothing else is configured.
Voyage API set VOYAGE_API_KEY Remote HTTP embeddings (voyage-3-lite, dim 512).
Local ONNX build --features local, then set RB_EMBED_BACKEND=local Downloads all-MiniLM-L6-v2 (dim 384) on first use via fastembed, at a pinned Hugging Face revision with SHA-256-checked files; inputs truncate at 512 tokens. Loading fails closed on a hash mismatch.

The embedding dimension AND model identity are fixed at first daemon init and checked fail-closed on every startup (vector reads are length-checked too); switching providers — or models, even at the same dimension — against an existing database refuses to run rather than silently mix vector spaces. For a deliberate model or dimension swap, stop all daemons and unmanaged SQLite clients sharing the database and take a database backup. Restart with rusty-brain serve --accept-model-change (or use RB_ACCEPT_MODEL_CHANGE=1 for auto-start), then unset the environment opt-in. Acceptance atomically replaces only the derived vector index and model/ dimension markers, preserving memory IDs, authored state, anchors, links and history. Run rusty-brain reembed repeatedly until scanned=0; skipped rows remain pending and need their underlying error fixed before retrying. Recall can be incomplete until all active rows have vectors in the new space; archived rows are not revived. Repeating acceptance for the same model/dimension preserves re-embedding progress.

Serving and explicit migration hold a cooperative database-inode admission lock across writer/read-pool lifetimes, including through hardlink/symlink aliases. It uses private sidecars in <OS-account-home>/.rusty-brain-db-admission, not a lock on SQLite's own file. The home comes from the effective OS account, not HOME, XDG or temporary-directory overrides; an unavailable or unsafe home fails closed. Never remove admission files while a daemon is running. Stop every pre-upgrade daemon before switching from the old /tmp lock location. Older binaries and raw SQLite clients do not participate: the offline stop requirement still applies. A legacy database with no global model marker adopts the configured model only when its corpus is empty or all rows name it; conflicting or mixed-model corpora require the explicit recovery path above.

Wire the MCP server into an agent

rusty-brain mcp speaks newline-delimited JSON-RPC (MCP) over stdin/stdout. Point an MCP-capable agent at it as a stdio server, for example:

{
  "mcpServers": {
    "rusty-brain": { "command": "rusty-brain", "args": ["mcp"] }
  }
}

It implements twelve tools. By default tools/list advertises the six-tool token-economy subset the model pays for every turn: remember, recall, get, context, update, and memory_feedback (report whether a recalled memory was helpful/wrong/stale, nudging its trust prior). The remaining six — list, graph, link (e.g. mark one memory as contradicting another), delete, history (bounded decision timeline plus the target's full stored source/evidence detail, identical to CLI JSON), and poll_changes (drains buffered change notifications) — are advertised only when RB_MCP_FULL_TOOLSET is set, though every tool stays routable when called directly.

Loopback HTTP API (optional, off by default)

For tools that speak neither MCP nor the CLI — dashboards, scripts in other languages, non-MCP agents — the daemon can serve an opt-in loopback-only HTTP listener that mirrors the wire operations:

rusty-brain serve --http                 # 127.0.0.1, ephemeral port (logged)
rusty-brain serve --http 127.0.0.1:7777  # explicit loopback bind
curl -s http://127.0.0.1:7777/ping \
  -H 'x-rusty-brain-namespace: global'
curl -s -X POST http://127.0.0.1:7777/recall \
  -H 'content-type: application/json' \
  -H 'x-rusty-brain-namespace: project:my-app' \
  -d '{"query": "auth token refresh decision", "limit": 5, "memory_type": null, "tags": []}'

Endpoints: GET /ping, GET /context, GET /memories/:id, POST /recall, POST /remember, POST /feedback, and a generic POST /ops that accepts the full tagged wire request ({"op": "Recall", ...}). Responses are the existing wire Response types as JSON. Wire errors map by kind — 400 (validation), 403 (permission_denied, incl. every admin op), 404 (not_found), 500 (internal, opaque). The HTTP gates add their own statuses: 400 for a missing/duplicated Host header or an absolute-form request line that disagrees with Host, 403 for a non-loopback Host or Origin, 404 for unknown paths, 405 with a per-path Allow header for wrong methods, 413 for bodies over 1 MiB, 415 for POSTs that are not application/json, and 503 when a request exceeds the overall deadline. The x-rusty-brain-namespace header is required on every route (global or project:name; absent = 400): it scopes the request — mirroring the mandatory UDS handshake namespace — and, being a custom (non-simple) header, forces any browser-initiated cross-origin request (including Origin-less no-cors GETs) into a CORS preflight that always fails, since the listener never emits CORS headers.

Security posture (see docs/THREAT_MODEL.md, "The opt-in HTTP listener"): off by default at every layer; the bind must be a literal loopback ip:port — anything else refuses to start; admin ops are always denied over HTTP (no kernel-verified peer credential over TCP); Host/Origin are checked against loopback (DNS-rebinding/browser defense); bodies are capped at 1 MiB; v1 is a same-machine surface intended for a single-user deployment and explicitly not an auth boundary — there is no same-user enforcement, so on a multi-user machine any local account can reach the non-admin surface while it is enabled.

Capture hooks (optional)

rusty-brain-install wires the rusty-brain-hooks binary into a supported agent CLI's hook configuration so that file edits, session starts/stops, and similar events are captured into memory automatically. The hooks are fail-open: handled errors and panics continue the session with exit status zero. This is not a whole-process latency guarantee; stdin, filesystem work, or stdout can stall. The agent surface is cross-agentic: OpenCode and Codex are first-priority targets alongside Claude Code, with Hermes discovery-gated. Per-agent setup, validation commands, and troubleshooting live in docs/AGENTS.md.

For OMP, run these commands from the project directory:

rusty-brain-install install --agents omp
rusty-brain-install status --agents omp
omp --model openai-codex/gpt-5.6-luna
# Remove only the intact, installer-owned extension:
rusty-brain-install uninstall --agents omp

The installer embeds a standalone .omp/extensions/rusty-brain.ts with an absolute hooks-binary path; no repository checkout or npm package is required. OMP global installation is intentionally unsupported. Reinstall and uninstall preserve unowned or locally modified files and report the conflict.

Current agent capability matrix:

Agent Adapter Capture Retrieval Config Scorecard Lifecycle source / limitation
claude-code stable supported supported supported unsupported Fixture-backed SessionEnd lifecycle under crates/rb-hooks/tests/fixtures/claude_code/; its scorecard runner is retired.
omp experimental supported supported supported supported Project-local native extension; OMP 18.2.4 Luna/Terra probes verify prompt recall, native write capture, and shutdown folding. Global install is unsupported; bounded evidence.
codex experimental partial unsupported partial unsupported Stop remains a no-op boundary until real fixtures prove a checkpoint or terminus; apply_patch capture is live-fixture-verified (openai/codex#16732 shipped in Codex 0.123.0).
opencode experimental supported unsupported unsupported unsupported session.idle folds via canonical SessionCheckpoint; bash and apply_patch file-edit capture are fixture-backed. Installer/plugin support is deferred.
gemini experimental partial unsupported partial unsupported Native SessionEnd remains canonical Stop; terminus mapping is descoped from the cross-CLI track.
hermes discovery unknown unknown unknown unsupported Discovery-gated; no hook names or config paths are hard-coded.

The scorecard runner is target-aware:

scripts/memory-scorecard.sh --agent omp --model @slow --runs 1
scripts/memory-scorecard.sh --agent codex --runs 1      # explicit skip today
scripts/memory-scorecard.sh --agent opencode --runs 1   # explicit skip today
scripts/memory-scorecard.sh --agent all --runs 1        # prints skips, then runs OMP

Configuration

Daemon knobs live in a user config file: ~/.config/rusty-brain/config.toml (or $XDG_CONFIG_HOME/rusty-brain/config.toml). Precedence, per knob:

CLI flag > environment variable > config file > built-in default.

Every binary — the CLI, the hooks, and the daemon — re-reads this file from disk itself, so a knob set here reaches auto-started daemons with no env forwarding. The auto-start env allowlist is therefore only secrets (VOYAGE_API_KEY, RB_ENRICH_API_KEY), identity fallback (USER/LOGNAME), and path resolution (HOME/PATH/XDG_*); the pre-existing knob env vars below stay supported for compatibility (env wins over the file), but new knobs are config-file-only. A missing file means all defaults; unknown keys warn and are ignored (forward compat); malformed TOML fails closed with a message naming the file. Secrets are deliberately env-only: the config file never holds credentials, and accept_model_change is deliberately not a file knob (consent must be explicit per model change).

# ~/.config/rusty-brain/config.toml — every key optional
socket_path = "/run/user/1000/rusty-brain/sock"
db_path = "/home/me/.local/share/rusty-brain/memory.db"
idle_timeout_secs = 60
jobs_config = "/home/me/.config/rusty-brain/jobs.toml"

[embed]
backend = "local"            # "local" forces the local ONNX provider

[enrich]
base_url = "http://localhost:11434/v1"
model = "llama3"             # both base_url and model required to activate

[search]
fusion = "linear"            # or "rrf" (Reciprocal Rank Fusion) for recall ranking
abstain_threshold = 0.22     # calibrated abstention bar (0.0 disables the gate)

[write_gate]                 # per-namespace write policy; the gate is on by
min_anchors = 0              # default for namespaces without their own entry
[write_gate.namespaces."project:rusty-brain"]   # namespace-scoped override
min_anchors = 1

[http]                       # opt-in loopback HTTP listener (off when absent)
enabled = true               # master opt-in; `bind` alone does NOT enable
bind = "127.0.0.1:7777"      # literal loopback ip:port only; non-loopback fails closed

(Exception to warn-and-ignore: unknown keys inside [retention], [http], and [write_gate] fail closed — a typo'd key in a section that mutates memories, opens a network listener, or drives a security policy must never silently no-op.)

Two further small files exist for namespace identity (and identity ONLY — a repo-committed file must never be able to set sockets, paths, or backends): a repo-committed .rusty-brain.toml at the git toplevel (namespace = "...") pins a project's namespace across clones — it is read from the blob committed at HEAD (git show HEAD:.rusty-brain.toml), so untracked or uncommitted edits are ignored with a warning until committed — and a per-user pin store (namespace-pins.toml under the user state dir) records CLAUDE.md frontmatter overrides accepted via rusty-brain --accept-namespace-override — unpinned overrides are never silently honored.

Variable Config-file key Purpose
RUSTY_BRAIN_DB db_path SQLite database path (default under the user data dir: ~/Library/Application Support on macOS, $XDG_DATA_HOME or ~/.local/share on Linux).
RUSTY_BRAIN_SOCKET socket_path Unix socket path for the daemon.
RUSTY_BRAIN_NAMESPACE — Skip namespace detection and use this namespace (same precedence as the global --namespace flag).
RUSTY_BRAIN_IDLE_TIMEOUT_SECS idle_timeout_secs Per-connection request idle timeout for the daemon (default 60; mainly for tests).
VOYAGE_API_KEY — (secret, env-only) Selects the Voyage embedding provider when set.
RB_EMBED_BACKEND embed.backend local forces the local ONNX provider (requires --features local).
RB_LOCAL_MODEL embed.local_model Local model name (implies local backend); defaults to all-MiniLM-L6-v2.
RB_ACCEPT_MODEL_CHANGE — (deliberately env/flag-only) Explicit model/dimension cutover after stopping all shared-DB clients (serve --accept-model-change); unset afterward and run reembed until scanned=0.
RB_ENRICH_BASE_URL, RB_ENRICH_MODEL enrich.base_url, enrich.model Optional LLM enrichment endpoint (off by default; heuristic enrichment is used otherwise).
RB_ENRICH_API_KEY — (secret, env-only) API key for the enrichment endpoint (optional, e.g. Ollama needs none).
RB_JOBS_CONFIG jobs_config Path to an evolution-jobs TOML config for serve (jobs are disabled if absent).
RB_FUSION_MODE search.fusion Recall fusion strategy: linear (default) or rrf.
RUST_LOG — Log verbosity (logs go to stderr; stdout is reserved for results).

Workspace layout

The repository currently contains 18 workspace crates. Each crate is small and single-purpose; dependencies form a compiler-enforced DAG. The evaluation and contract-guard crates are development/CI tooling rather than shipped runtime components.

Crate Responsibility
rb-types Domain vocabulary: MemoryId, Namespace, MemoryNote, errors, enums.
rb-config Shared configuration, namespace resolution, and path precedence.
rb-store SQLite + sqlite-vec engine: schema, migrations, FTS, vector KNN, graph queries.
rb-proto Daemon wire protocol: request/response types, length-delimited JSON framing, socket client.
rb-embed EmbeddingProvider trait + deterministic / Voyage / local (feature-gated) providers.
rb-search Pure hybrid ranking functions (Linear and RRF).
rb-engine Per-request orchestration: enrich → embed → store → link → recall.
rb-enrich Opt-in LLM enrichment and semantic linking (heuristic offline by default).
rb-daemon Single-writer service: writer thread, read pool, socket listener, change broadcast, namespace isolation.
rb-mcp MCP stdio adapter (the 12 tools; six advertised by default).
rb-redact Shared secret-redaction pass (rules + entropy sweep) for capture and scrub.
rb-tokens Shared token counting used by prompt and MCP tool-budget guards.
rusty-brain The rusty-brain binary: serve, mcp, and client subcommands.
rb-agents CLI-agnostic agent hook spine: event model and per-CLI adapters.
rb-hooks The rusty-brain-hooks capture binary (fail-open).
rb-install The rusty-brain-install binary: wire/unwire hooks into agent CLIs.
rb-eval (dev-only) Retrieval regression harness with deterministic and recorded real-model embeddings; excluded from the shipped binary.
rb-contract-guard (CI/dev-only) Detects protocol/schema drift and requires an explicit compatibility decision.

Development

Install the local supply-chain gate with brew install cargo-deny on macOS (or cargo install cargo-deny --locked). cargo deny check uses deny.toml, including its all-features graph, for the same advisory, license, ban, and source policy enforced by CI. An installed tool is not a clean verdict: investigate any findings instead of adding blanket exceptions.

When changing the MCP registry, review overview tool counts manually: the runtime tests exposes_exactly_the_twelve_tools and advertised_default_set_is_the_token_economy_subset guard the exact routable and default-advertised sets, not documentation wording. The current surface is 12 routable tools, six advertised by default. Workspace/PRD prose is reviewed against the manifest and delivery evidence rather than pinned by source-text assertions.

Optional local compiler caching: brew install sccache, then merge the following into your user ~/.cargo/config.toml (not the repository):

[build]
rustc-wrapper = "sccache"
incremental = false # rustc incremental compilations cannot be cached by sccache

Keep sccache on PATH. On macOS the default disk cache is ~/Library/Caches/Mozilla.sccache, capped at 10 GiB with least-recently-used eviction. Inspect it with sccache --show-stats; configure [cache.disk] in ~/Library/Application Support/Mozilla.sccache/config to change dir or size (bytes), then restart the server with sccache --stop-server before the next build. The wrapper primarily reuses unchanged compilation inputs, not linking or arbitrary source edits. To compare with Cargo's native incremental mode for one build, use RUSTC_WRAPPER= CARGO_INCREMENTAL=1 cargo build --workspace. See Vega build tooling for measured cache results, verification evidence, and the current supply-chain finding triage.

cargo build                                                   # default (lean) build
cargo build -p rusty-brain --features local                   # with local ONNX embeddings
cargo test --workspace                                        # all tests
cargo test -p rb-eval                                         # ranking regression harness
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all --check
cargo deny check                                              # supply-chain / license policy

Conventions:

  • Workspace lints deny unwrap, expect, and panic by default, with a few narrow, explicit per-module exceptions (e.g. panic-recovery and test-support seams); unsafe is warned. Shipped request paths return errors, they don't panic.
  • Migrations are append-only and checksummed; a CI gate rebuilds a fresh database from committed SQL and exercises every query path.
  • Commits follow Conventional Commits.

Testing

The current test suite covers correctness and bounded retrieval quality, not portable performance:

  • Unit and integration tests across the workspace cover type invariants, ranking determinism, protocol round-trips, the FTS/vector/graph query paths, migration reproducibility, concurrency and namespace isolation, and the MCP contract.
  • rb-eval keeps the deterministic ranking-regression harness and now also runs a strict offline production-embedding gate: committed real local-model vectors over 205 memories, 72 goldens, and an untouched 20-query holdout must clear preregistered recall@5/MRR/NDCG/dedup/channel floors with exact document/query input kinds and zero replay fallbacks. A scheduled five-instant comparison keeps Linear as the default; RRF currently regresses MRR/NDCG.
  • Bounded N=5 capability scorecard: the 2026-07-12 Claude Code recovery run was safe with zero memory-induced errors; reach and freshness passed and capture missed its steelman comparison. Its Class A rows used a privileged importance-8 target against importance-5 off-topic distractors and did not attribute startup versus query evidence, so they are historical response/cost data, not retrieval-at-scale proof. A corrected reread remains outstanding. This is small-sample proxy evidence, not a user-adoption study. See docs/eval/2026-07-12-w35-scorecard-n5-run.md.
  • Nightly real-agent smoke (.github/workflows/nightly-claude-smoke.yml): a scheduled macOS job drives a real headless Claude Code session (claude -p) against freshly built binaries with hooks + MCP installed into an isolated HOME, then proves capture → idle → recall against exactly one daemon and one 0600 database, and greps the raw DB bytes for a planted fake AWS key (zero plaintext hits, redaction marker present). It is scheduled-only — it never gates PRs — and on failure it opens or updates a pinned issue titled "nightly claude smoke failing". It requires the ANTHROPIC_API_KEY repository secret (small spend: the session runs --model haiku --max-budget-usd 1). Run it locally with scripts/nightly-claude-smoke.sh --bin-dir target/release.
  • Coverage is measured on demand, not gated in CI: 93.2% of lines across the workspace at cfc9b23, with per-crate numbers, the reproduce commands and the no-gate rationale in docs/eval/2026-10-18-coverage-baseline.md.

Not yet measured: portable performance and latency; large-corpus scale; sustained concurrency; resource exhaustion and partial outages; Voyage quality; and multi-user/multi-machine activation or adoption. The semantic gate measures the supported local model at the authored 205-memory scale; it is not a scale benchmark or a real-world value study.

Roadmap

Implemented: store/recall, the daemon, MCP and CLI surfaces, agent capture hooks, composite embeddings, RRF, confidence and usefulness feedback, contradiction surfacing, supersession, opt-in maintenance jobs, and real-model replay evaluation. Designed but not yet built:

  • LLM-assisted memory evolution (reconciliation and reflection) beyond the deterministic consolidation, decay, and importance-recalibration jobs that already ship.
  • A networked / multi-host surface with real authentication (today it is single-machine and per-user).
  • An ANN vector index for larger corpora (sqlite-vec brute-force KNN is the documented current limit).

License

Released under the MIT License.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages