An active, Obsidian-native, Git-backed memory system for AI agents.
Named in homage to Marvin Minsky and his foundational book The Society of Mind, Marvin turns ephemeral LLM context windows into a durable, topologically connected knowledge base. It is the reference implementation of the research paper K-Lines: A Cognitively-Grounded Four-Memory Architecture for Persistent Conversational AI (and its companion repository).
Headline results on LongMemEval-S (500 questions, ~115k-token haystacks): 99.6% recall_any@5 retrieval, and 82.8% end-to-end QA accuracy with a fully local, quantized reader — within ~10 points of frontier-cloud-reader systems, with zero LLM calls on the write or query path and no cloud dependency. Full numbers →
Most agentic "memory skills" dump chat logs into a hidden SQLite database or a black-box vector store. That works for casual chatbots, but breaks down in professional workflows. When you take your agent's memories seriously, you need ergonomics, interpretability, and safety.
Marvin writes every memory as a clean, human-readable Markdown file with YAML frontmatter, organized into Episodic/, Semantic/, Procedural/, and Reflective/ folders. Point Obsidian at the vault and you get a visual graph of everything your agent has learned. You can edit, co-author, and browse the knowledge base alongside your AI.
Agents hallucinate and explore dead ends. Because the vault is natively backed by Git, agents check out isolated worktree branches for risky tasks: merge on success, discard on failure. Every memory write is a commit — git blame, git diff, and git revert work on your agent's thoughts. A polluted memory is one revert away from clean, not a database surgery project.
Biological memory is consolidated during sleep. Marvin's background Brain Worker (driven by a NATS broker) extracts entities via langextract, injects [[Wikilinks]], and runs a two-phase consolidation with a local LLM: entity-scoped semantic facts are distilled from raw episodic logs, then cross-fact reflective insights are synthesized per aspect. Your agent's write path stays fast; the thinking happens offline.
| Kind | Holds | Mechanism |
|---|---|---|
| Episodic | Raw events: tasks, bugs, sessions | Logged fast, marked consolidated once distilled |
| Semantic | Durable facts | Structured facts (predicate / value / aspect / confidence); a new value for the same predicate soft-deprecates the old one — auditable, never silently overwritten, excluded from retrieval |
| Procedural | Playbooks and rules | Plain procedures, plus K-line templates: response strategies with trigger conditions (intents / styles / entity types / keywords), selected by weighted partial-match scoring and ranked by adaptive effectiveness |
| Reflective | Cross-cutting insights | Synthesized from accumulated facts during sleep, with provenance links |
- Obsidian-Native Vault — clean Markdown + YAML frontmatter; full graph visualization in Obsidian.
- Git-Backed Worktrees — branch memory for risky tasks; merge on success, discard on failure.
- Structured Semantic Facts — stable fact IDs, predicates, aspects, confidence, and soft deprecation with
replaced_bylinking. - K-Line Procedural Templates — Minsky-style partial reactivation: weighted trigger scoring plus an ACT-R-style utility (usage count + effectiveness EMA), surfaced automatically by
marvin_prepare_session. - Deep Semantic Graphing — zero-shot entity extraction with automatic
[[Wikilink]]injection; the wikilink graph feeds retrieval. - Computational Sleep — two-phase background consolidation using local open-weight models (default
qwen3.6:35b-a3b-q4_K_Mvia Ollama). - Hybrid Retrieval — three-stream Reciprocal Rank Fusion (SQLite FTS5 +
sqlite-vecdense vectors + IDF-weighted entity graph), optionalbge-reranker-v2-m3cross-encoder (int8 on CPU, fp16 on GPU), and opt-in time-aware freshness decay. - MCP Gateway — 20 tools (the full service surface) over SSE (port 8421) or stdio; plugs into any MCP-compatible agent.
- AXI CLI — the same functionality as an axi.md-style command line: token-efficient TOON output, a live dashboard on bare
marvin,help[]next-step hints, structured errors. Built for agents driving a shell, pleasant for humans. - Reproducible Benchmark — built-in LongMemEval-S harness for retrieval and end-to-end QA, so memory changes are measured, not vibed.
LongMemEval-S, cleaned release, all 500 questions. Retrieval: hybrid three-stream RRF + cross-encoder rerank. QA: top-10 retrieved sessions read by a local qwen3.6:35b-a3b (q4_K_M) with JSON + Chain-of-Note, graded under the official per-question-type judge protocol.
| Metric | Score |
|---|---|
recall_any@5 |
99.6% |
| NDCG@10 | 95.3% |
| MRR | 95.5% |
| End-to-end QA accuracy (local reader) | 82.8% |
Two facts worth knowing: the published SOTA cluster (90–93%) is driven by frontier cloud readers, and in our controlled ablation the same local reader scores 45.8% when handed the full ~126k-token history versus 81.2% with Marvin's retrieved top-10 (~16k tokens) — the memory layer is what makes a local model accurate at all. Reproduction commands, per-type breakdowns, and the judge protocol are in the evaluation guide.
Marvin runs as four lightweight services orchestrated by Docker Compose:
| Service | Role |
|---|---|
| MCP Gateway | FastMCP server exposing 20 tools via SSE on port 8421. The low-latency edge your agent talks to. |
| NATS | High-performance message broker with JetStream. Streams memory.created and memory.sleep events. |
| Brain Worker | Background daemon subscribing to NATS. Runs entity extraction (langextract) and two-phase sleep consolidation. |
| Ollama | Bundled local LLM container. Cost-free inference for the Brain Worker's consolidation phases. |
+-----------+ MCP (SSE / stdio) +--------------------+
| | -------------------------------->| |
| Agent | | MCP Gateway | ---> (Writes) ---> [ Git-Backed Vault ]
| | <------------------------------- | (FastMCP API) | <--- (Reads) <--- [ SQLite-Vec Index ]
| | (Search / Tools) +--------------------+
+-----------+ |
[ Publish 'memory.created' ]
[ Publish 'memory.sleep' ]
v
+--------------------+
| NATS Broker |
+--------------------+
|
[ Consume Events ]
v
+--------------------+
| | ---> (Extract Entities) -> [ LangExtract ]
[ Local Ollama ] <--- (Consolidate 2-phase) --| Brain Worker |
| | ---> (Update Links & Commit to Vault)
+--------------------+
More detail in ARCHITECTURE.md and the docs site.
uv tool install git+https://github.com/r0k3/marvinYou immediately have the AXI command line:
marvin remember "DB" --predicate storage --value "PostgreSQL with asyncpg"
marvin search "postgres" # TOON output: hits[1]{title,kind,path}: ...
marvin skill install # teach your agent when to use all thisBare marvin is a live dashboard, not help text — token-efficient TOON your agent (or you) can read at a glance:
$ marvin
vault:
path: ~/.marvin_vault
notes: 42
episodic: 17
semantic: 18
procedural: 4
reflective: 3
unconsolidated_episodes: 5
indexed: 42
recent[3]{title,kind,path}:
Fixed race in worker,episodic,Episodic/Fixed race in worker.md
...
help[4]:
marvin search <query> # hybrid recall across all four memory types
marvin consolidate # distill 5 unconsolidated episodes
...
And the MCP server for your agent:
{
"mcpServers": {
"marvin": {
"command": "marvin",
"args": ["serve", "--vault-path", "~/.marvin_vault", "--transport", "stdio"]
}
}
}This gives you the vault, hybrid retrieval, and all 20 tools — without the background worker.
Prerequisites: Docker and Docker Compose.
git clone https://github.com/r0k3/marvin.git
cd marvin
# Start the Marvin cluster
docker compose up -d
# Pull the local consolidation model (one-time; any litellm-supported model works)
docker exec -it marvin-ollama-1 ollama pull qwen3.6:35b-a3b-q4_K_MThe MCP Gateway is now listening on http://localhost:8421/sse.
uv pip install 'marvin[gpu]' # Linux + NVIDIA (CUDA 12.x): embeddings + fp16 reranker on GPUAdd to ~/.config/goose/config.yaml:
extensions:
marvin:
enabled: true
type: sse
name: marvin
uri: http://localhost:8421/sseAdd to .cursor/mcp.json:
{
"mcpServers": {
"marvin": {
"url": "http://localhost:8421/sse"
}
}
}Add to your MCP config:
{
"mcpServers": {
"marvin": {
"type": "sse",
"url": "http://localhost:8421/sse"
}
}
}Marvin ships with a first-class agent skill (marvin-memory) that teaches the agent when to use memory without being told: which signals to store (and as which memory type), recall-before-answering, closing the template feedback loop after "that worked", session lifecycle, and what never to store. It covers both surfaces — the marvin_* MCP tools and the CLI — and was pressure-tested against baseline agent behavior.
marvin skill install # → ./.claude/skills/marvin-memory (Claude Code, project)
marvin skill install --user # → ~/.claude/skills/marvin-memory
marvin skill show # print SKILL.md to paste into any other harnessSource: src/marvin/skill/SKILL.md.
uv run python -m marvin.eval.demoRuns annotated four-memory retrieval over the bundled A Midsummer Night's Dream vault (examples/demo_vault) — episodic scenes, semantic facts, a procedural analysis strategy, and a reflective insight, each answering the query type it should.
Full documentation is at r0k3.github.io/marvin:
- Getting started — install, Docker cluster, agent configs
- MCP tools reference — all 20 tools
- CLI reference (AXI) — every command, TOON format, exit codes, session-hook pattern
- The agent skill — what
marvin-memoryteaches and the test-first evidence behind it - Architecture and evaluation methodology
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
If you use Marvin in your research, please cite the paper:
Kende, Robert, K-Lines: A Cognitively-Grounded Four-Memory Architecture for Persistent Conversational AI (February 06, 2026). Available at SSRN: https://ssrn.com/abstract=6234218 or http://dx.doi.org/10.2139/ssrn.6234218
@misc{kende2026klines,
author = {Kende, Robert},
title = {K-Lines: A Cognitively-Grounded Four-Memory Architecture for Persistent Conversational AI},
year = {2026},
month = feb,
howpublished = {SSRN},
doi = {10.2139/ssrn.6234218},
url = {https://ssrn.com/abstract=6234218}
}MIT — see LICENSE for details.