Membrick

Open-source agent memory for coding agents.

AI memory that knows what is still true. Your agent doesn't just forget; it can confidently remember outdated decisions.

Membrick is an open-source persistent agent memory layer for Claude Code, Codex, Gemini CLI, Antigravity CLI (AGY), and Muse Code. It turns project history — sessions, documents, decisions, traces, notes, and code — into current, evidence-backed context when an agent needs it.

Search can find the right topic. Membrick helps an agent answer the harder question: is this information still true? It uses relevance, time, and semantic relationships to distinguish the latest truth from old-but-still-relevant history.

Agent memory guide · Quickstart · Reproducible demo · Agent integrations · Benchmarks · Documentation

Current benchmark: 500-question LongMemEval-S. See the latest benchmark results for metrics and the source report.

The stale-memory problem

Your project says one thing on Monday and something different on Friday. Both versions remain relevant to the same question.

Older — decision-a.md

# Gateway Retry Policy

Gateway timeout retry attempts: 5.

Newer — decision-b.md

# Gateway Retry Policy

Gateway timeout retry attempts: 2.

Now ask:

How many retry attempts should we use for gateway timeouts?

A normal retriever can return either document — or both — and leave the model to guess which value is current.

Membrick keeps 2 as the current answer and preserves 5 as superseded history.

That difference matters anywhere project truth changes over time: architecture decisions, API contracts, configuration values, runbooks, ownership, terminology, and implementation plans.

There is no required supersedes: frontmatter in this example. For simple configuration/value claims, Membrick can infer chronological replacement when the documents establish the same semantic domain. Inferred supersession is domain-scoped so unrelated settings such as two different services' timeout values do not suppress one another. Explicit supersession metadata remains authoritative when you provide it.

membrick query \
  "How many retry attempts should we use for gateway timeouts?" \
  examples/demo-real-terminal

Current-state retrieval returns the newer decision with semantic_status: current, and membrick context excludes the stale value.

Reproducible terminal demo

The repository includes a reproducible asciinema PTY recording that builds the actual membrick binary, sets deterministic file mtimes for a controlled stale-memory scenario, runs the neutral query above, verifies the result, and renders the captured terminal session.

bash scripts/run_real_terminal_demo.sh

See examples/demo-real-terminal/ and .github/workflows/demo-real-terminal.yml.

Why Membrick?

Agent memory is not only a retrieval problem. It is a state problem.

A useful memory layer has to answer:

1. Relevance — is this about the question?
2. Recency — when was this evidence true?
3. Supersession — did something newer replace it?
4. Temporal intent — is the user asking about now, last Tuesday, or a historical state?
5. Evidence — where did the answer come from?

Historical evidence is not deleted. A historical query can still retrieve superseded material as history rather than presenting it as current state.

Quickstart

Install directly from GitHub:

cargo install --git https://github.com/RooAGI/Membrick

Check what is currently indexed in a folder without scanning it:

membrick status .

Check or index a local corpus:

membrick review /path/to/repo

Query it:

membrick query "what is the current retry policy?" /path/to/repo/docs

Get LLM-ready context:

membrick context "what is the current retry policy?" /path/to/repo/docs

See the CLI reference and full quickstart for Docker, HTTP, Python, Rust, and MCP setup.

Agent integrations

Membrick provides opt-in integrations for major coding-agent clients.

Build the Claude Code and Codex integrations:

cargo build --release --features claude-code,codex
./target/release/membrick install claude /path/to/project
./target/release/membrick install codex /path/to/project

All agents share one project-scoped memory store:

/path/to/project/.membrick/memory/

Upgrading from an older version? Legacy per-provider stores (.membrick/claude-memory/, .membrick/codex-memory/, .membrick/gemini-cli-memory/, .membrick/agy-memory/, .membrick/muse-memory/) are migrated into .membrick/memory/ on first run and removed once their migration succeeds.

The shared MCP controls include session recording, memory listing, and runtime enable/disable controls:

mcp__membrick__record_session       {"action":"start|stop|status"}
mcp__membrick__list_memories        {"limit":20}
mcp__membrick__enable_membrick       {}
mcp__membrick__disable_membrick      {}
mcp__membrick__membrick_status        {}

See agent integrations and the MCP guide for the complete setup.

Benchmark highlights

Membrick is evaluated on LongMemEval-S, a public benchmark for long-context agent-memory retrieval over multi-session conversations.

How to read the benchmark numbers

Separate integration smoke runs use a matched routing-decision-supersession task template. The one-run Codex result showed 37.4% fewer reported continuation tokens with Membrick hooks. The Claude run is invalid: both legacy .lint-ai and current .membrick directories were present, so its hooks failed open and continuation retrieved no memory. See the Codex and Claude Code reports. These are diagnostics, not release benchmarks; compare each provider only with its own native baseline.

Every result has three independent labels:

1. Scope: the 500-question aggregate evaluates the full scoped dataset; the 133-question segmented comparison evaluates only the multi-session slice.
2. Metric: fractional (regular) recall measures the fraction of all gold sessions recovered; any-hit recall counts a question as successful when at least one gold session is recovered.
3. Cutoff: @5, @10, and @20 mean the top 5, 10, or 20 returned results. A Recall@5 value must not be compared with Recall@10 without checking both the metric type and benchmark scope.

Why two benchmark tables?

The 500-question aggregate is the public overall headline. It runs the heuristic global path across every LongMemEval-S question category. The 133-question segmented comparison isolates the multi-session category and uses the same question subset for fixed segmented, adaptive segmented, and single-index baselines. The single-index row is therefore the fair control for segmented routing—not a second overall headline.

Because the scopes and query mix differ, their recall and latency values must not be compared as a time series or combined into one score.

The current benchmark uses the repository's raw LongMemEval-S dataset, runs 500 question-scoped queries through the heuristic backend, enables structured-fact retrieval, and uses no embedding vectors. This latest result is a release-candidate run, not a tagged-release measurement.

500 questions · heuristic backend · single CPU · no GPU

LongMemEval-S, 500 questions · 2026-10-15 · single index · heuristic NER · structured-fact retrieval · no embeddings Working-tree run based on b204b7e; not a clean release measurement.

Source report: retrieval-longmemeval-500-2026-10-15-v0.6.0-b204b7e-working-tree.json.

Fractional Recall@k is the average fraction of all correct answer sessions recovered in the top k. Any-hit Recall@k counts a query as successful when any correct answer session appears in the top k.

Search latency measures the MemoryService::search call and excludes indexing the question's haystack. The older published 13.0 ms figure used a different timing scope and is not directly comparable. See the latest 500-question report and benchmark details.

The repository keeps the dataset downloader, production-style benchmark binary, shared AgentMemory scorer, comparison workflow, and temporal-reasoning experiment harnesses so results can be reproduced and changes can be evaluated without silently changing the query path.

See benchmark methodology, benchmark results, and comparison methodology.

Latest segmented-index comparison

The v0.6.2 segmented comparison uses all 500 LongMemEval-S questions, Tantivy 0.25.0, and heuristic NER. It compares the server-default LocalDistinctiveness router with the experimental coverage-local router. Both runs use fixed top-5 and adaptive expansion up to 12; the server default remains fixed top-3. Timings are direct-index measurements and exclude haystack indexing.

The October 5 README value of 86.77% Fractional Recall@5 came from an older coverage-local run; the latest coverage-local rerun is 86.84%. On the server-default router, fixed top-5 scored 82.38%. The fused coverage-local route had the highest retrieval scores in this comparison, with higher mean latency. Latency is sensitive to run conditions, so treat it as diagnostic. These direct-index timings are not comparable to the standalone MemoryService timing above. Dataset SHA-256: 08d8dad4be43ee2049a22ff5674eb86725d0ce5ff434cde2627e5e8e7e117894. See the benchmark results and segmented-index design. Full report: LocalDistinctiveness · coverage-local.

Integration smoke measurements

The repository also includes reproducible Claude Code and Codex replay/performance tests. These are diagnostic one-run measurements, not universal performance guarantees.

Read the full conditions and limitations:

• Claude Code performance tests
• Codex performance tests
• Comparison methodology
• Session metrics

What Membrick can do

• Recover the right past session or project note when an agent needs context
• Rank current evidence ahead of superseded guidance
• Infer simple chronological configuration updates inside an established semantic domain
• Preserve historical evidence for historical questions
• Resolve relative-time queries against an explicit reference date when one is available
• Catch contradictions before they spread
• Detect terminology drift across documents
• Find orphaned or weakly linked pages
• Query facts, entities, symbols, ownership, and time
• Build review packets from changed files and related semantic context
• Feed grounded context into an LLM instead of raw text blobs
• Keep agent memory inspectable and local to the project

How it works

Membrick treats project memory as more than a bag of text.

Sessions · docs · code · traces
            │
            ▼
        1. Ingest
            │
            ▼
 Facts · entities · symbols · time
            │
            ▼
      2. Understand
            │
            ▼
 Links · ownership · supersession
            │
            ▼
       3. Connect
            │
            ▼
 Ranked · sourced · current context
            │
            ▼
       4. Retrieve

Under the hood, Membrick builds a lexical index plus sparse entity/term tables and overlays graph structure for links, symbols, ownership, semantic relations, and time.

A single prepared-query path owns query analysis, augmented search text, temporal context, routing intent, reference-clock handling, semantic suppression, and provenance annotation. The CLI and IndexStore use the same semantic/temporal query policy so current-state behavior does not depend on which high-level entry point you call.

The same corpus model powers review-oriented checks such as missing cross-references, orphan pages, low-confidence claims, stale knowledge, and semantic drift.

For implementation details, see:

• Chunk strategy
• Lexical data
• Artifact indexing
• Shared integration architecture

Use Membrick from your stack

CLI

membrick query "what is the current retry policy?" /path/to/repo

Docker / HTTP

export SERVER_TOKEN=local-dev-token
docker compose up --build -d
curl http://127.0.0.1:8080/health

See the HTTP server guide.

Python

Install the PyPI package to get both the Python MemoryService API and the Rust membrick CLI on supported platforms:

pipx install membrick
membrick install codex .

For development from this checkout, build the optional Python extension with uv and maturin:

uv venv --python 3.10
source .venv/bin/activate
uv pip install "maturin>=1.9.4,<2"
maturin develop --release --uv

To build a distributable wheel instead, run maturin build --release; the wheel is written under target/wheels/.

import membrick

memory = membrick.Memory(path="./memory-index")
memory.add(
    "request-1",
    "user-1",
    "session-1",
    [{"role": "user", "content": "Docker runs on Ubuntu hosts"}],
)
print(memory.search("docker ubuntu", "user-1", 5))

# Use the same API against a running membrick server:
# NOTE: base_url must be passed by keyword. A positional first argument
# is `path` and would silently create a local index instead of connecting.
remote = membrick.Memory(base_url="http://127.0.0.1:8080", api_key="local-token")
print(remote.search("docker ubuntu", "user-1", 5))

Rust

MemoryService is the only public memory access API. Request, response, document, and configuration types are public; stores, indexes, snapshots, builders, and persistence modules are internal. See the API migration guide.

use membrick::{MemoryService, PipelineOptions, SourceDocument};

fn main() -> anyhow::Result<()> {
    let mut memory = MemoryService::in_memory(PipelineOptions::default());

    memory.upsert(SourceDocument::with_stable_doc_id_from_source(
        "docs/install.md".to_string(),
        "Docker install guide for Linux hosts".to_string(),
        "docker install".to_string(),
        None,
        vec!["Overview".to_string()],
        vec![],
        None,
        None,
    ));

    memory.refresh()?;
    let results = memory.search_with_filters("docker install", "workspace", None, 5, &Default::default())?;
    println!("{}", serde_json::to_string_pretty(&results)?);
    Ok(())
}

See docs/quickstart.md for complete examples.

When is Membrick a good fit?

Membrick is especially useful when you maintain:

• Long-running agent memory over conversations, notes, and decisions
• Markdown knowledge bases with many cross-links
• Internal documentation where terminology and decisions drift over time
• Codebases where symbols, ownership, usage, and review context matter
• Fast-changing corpora where freshness matters as much as relevance

If your only requirement is simple keyword search over a static set of documents, Membrick is probably more machinery than you need.

Project status

Membrick is under active development. The release query path uses the heuristic backend; experimental model-backed query semantics remain separate from the audited release dependency graph.

The security audit workflow runs cargo audit. Binary persistence uses oxicode, and the lexical index uses Tantivy 0.25 to preserve measured recall. Current audits report only transitive Tantivy warnings in lru and memmap2; these are tracked for upstream fixes.

Issues, benchmark reproductions, integration feedback, and contributions are welcome.

• Open an issue
• Join a discussion
• Read the documentation

License

Apache-2.0