{
  "markdown": "# Ori Mnemos\n\n**Open-source persistent memory infrastructure for AI agents.**\n\nOri implements human cognition as mathematical models on a knowledge graph. Activation decay from ACT-R. Spreading activation along wiki-link edges. Hebbian co-occurrence from retrieval patterns. Reinforcement learning on retrieval itself. Recursive graph traversal with sub-question decomposition. The system learns what matters, forgets what doesn't, and optimizes its own retrieval pipeline.\n\nPersistent memory across sessions, clients, and machines. Zero-infrastructure retrieval that [matches and in several cases strongly outperforms incumbents on benchmarks](#benchmarks) — and you own every byte of your data. Markdown on disk. Wiki-links as graph edges. Git as version control. No database lock-in, no cloud dependency, no vendor capture.\n\n**v0.6.0** · [npm](https://www.npmjs.com/package/ori-memory) · [Paper](https://orimnemos.com/rmh) · Apache-2.0\n\n---\n\n## Benchmarks\n\n### HotpotQA — Multi-Hop Retrieval\n\nHead-to-head against [Mem0](https://github.com/mem0ai/mem0), the most widely adopted agent memory system. HotpotQA tests multi-hop reasoning — questions that require connecting information across multiple documents to answer.\n\n| Metric | Ori Mnemos | Mem0 | Δ |\n|--------|:----------:|:----:|:-:|\n| Recall@5 | **90%** | 29% | **3.1×** |\n| F1 Score | **0.68** | 0.33 | **2.1×** |\n| Latency (avg) | **120ms** | 1,140ms | **9.5× faster** |\n| Infrastructure | Markdown + SQLite | Redis + Qdrant + cloud | — |\n\nOri retrieves the right information 3× more often, scores 2× higher on answer quality, and does it 9.5× faster — on markdown files with a SQLite index. No cloud services. No API keys. Full evaluation code in [`bench/`](./bench/).\n\n### LoCoMo — Long-Term Conversational Memory\n\nEvaluated on [LoCoMo](https://github.com/snap-research/locomo) (Maharana et al., 2024) — the standard benchmark for long-term conversational memory. 10 conversations, 695 questions across single-hop, multi-hop, and temporal reasoning.\n\n| System | Single-hop | Multi-hop | Infrastructure |\n|--------|:----------:|:---------:|----------------|\n| MemoryBank | 5.00 | — | Custom server |\n| ReadAgent | 9.15 | — | LLM-based |\n| A-Mem | 20.76 | — | Cloud APIs |\n| MemGPT / Letta | 26.65 | — | PostgreSQL + cloud |\n| LangMem | 35.51 | 26.04 | Cloud APIs |\n| OpenAI Memory | 34.30 | — | OpenAI proprietary |\n| Zep | 35.74 | 19.37 | PostgreSQL + cloud |\n| **Mem0** | **38.72** | **28.64** | Redis + Qdrant + cloud |\n| **Ori Mnemos** | **37.69** | **29.31** | **Markdown on disk** |\n\nBaseline numbers from [Mem0 paper](https://arxiv.org/abs/2504.19413) (Table 1). Ori evaluated with GPT-4.1-mini for answer generation, BM25 + embedding + PageRank fusion for retrieval.\n\nMore benchmarks coming — including [LoCoMo-Plus](https://github.com/snap-research/locomo) (Level-2 cognitive memory) and adversarial refusal evaluation.\n\n---\n\n## Quick Start\n\n```bash\nnpm install -g ori-memory\nori init my-agent\ncd my-agent\n```\n\nConnect to your agent:\n\n```bash\n# Full adapters — auto-orient at session start, capture at session end\nori bridge claude-code --vault ~/brain                 # hooks + MCP + CLAUDE.md\nori bridge hermes --vault ~/brain                      # native plugin + MCP + HERMES.md\nori bridge opencode --vault ~/brain                    # plugin + MCP + AGENTS.md\n\n# MCP-only adapters — tools available, no lifecycle automation\nori bridge cursor --vault ~/brain                      # .cursor/mcp.json\nori bridge codex --vault ~/brain                       # ~/.codex/config.toml\n\n# Any MCP client\nori bridge generic --vault ~/brain                     # prints config for manual setup\n```\n\nClaude Code, Hermes Agent, and OpenCode get full lifecycle integration — the agent orients at session start, captures insights at session end, and validates notes on write. Cursor, Codex, and other MCP clients get access to all 16 tools but manage their own session lifecycle.\n\nManual MCP config (works with any client that speaks MCP):\n\n```json\n{\n  \"mcpServers\": {\n    \"ori\": {\n      \"command\": \"ori\",\n      \"args\": [\"serve\", \"--mcp\", \"--vault\", \"/path/to/brain\"],\n      \"env\": { \"ORI_VAULT\": \"/path/to/brain\" }\n    }\n  }\n}\n```\n\nStart a session. The agent receives its identity automatically and begins onboarding on first run.\n\n---\n\n## What's New\n\n**v0.6.0 — Navigated Recursion.** `ori explore` no longer returns a flat synthesis. The agent sees the decomposition tree — which branches produced results, which hit dead ends — and steers the traversal itself. New session commands: `explore-start`, `explore-expand`, `explore-conclude`. Budget is a nudge, not a wall: soft exhaustion with explicit extension. A cross-encoder reranking stage now sits on top of four-signal fusion. RMH Constraint 2 goes from partial to real.\n\n```\n$ ori explore-start \"why did we choose SQLite over postgres\"\n\nexploration e7f2 — 3 branches\n├─ [1] storage engine tradeoffs        4 notes, strong signal\n├─ [2] deployment constraints          2 notes\n└─ [3] prior migration decisions       dead end — no notes\n\nnext: ori explore-expand e7f2 1   |   ori explore-conclude e7f2 --answered\n```\n\n**v0.5.6 — OpenCode bridge.** Full lifecycle integration: first-run onboarding, auto session capture, note validation, multi-vault support. `ori bridge opencode` — one command.\n\n**v0.5.5 — Ebbinghaus warmth.** Notes accessed once fade fast (half-life ~7 days). Notes accessed across many sessions embed deeply (up to ~28 days). Short-term and long-term memory, structurally distinct.\n\nFull history in the [CHANGELOG](./CHANGELOG.md).\n\n---\n\n## Recursive Memory Harness\n\nOri is the first implementation of the **Recursive Memory Harness** (RMH) framework — a set of constraints on how persistent memory should behave for AI agents.\n\nThe core insight comes from Recursive Language Models ([Zhang, Krassa & Khattab, 2026](https://arxiv.org/abs/2512.24601)). RLM treats context not as input to be stuffed into a window, but as an environment to be navigated. The model doesn't get a bigger desk — it gets legs and walks into the library. RMH applies the same principle to persistent memory.\n\nThree constraints define the framework:\n\n1. **Retrieval must follow the graph.** Memory is not a flat vector store. Notes are nodes, wiki-links are edges. Retrieval walks the structure — Personalized PageRank at α=0.45, spreading activation along edges, community-aware traversal. The topology of the graph shapes what gets found.\n\n2. **Unresolved queries must recurse.** When a single retrieval pass is insufficient, the system decomposes the question into sub-questions, retrieves against each, and synthesizes. Convergence detection stops recursion when new passes stop surfacing new information. This is what `ori explore` does.\n\n3. **Every retrieval must reshape the graph.** Retrieval is not read-only. Co-occurrence edges grow between notes retrieved together (Hebbian learning). Q-values update based on whether retrieved notes were actually useful. The graph learns from how it is used — every query makes the next query better.\n\nMost memory systems treat retrieval as search. RMH treats retrieval as navigation, recursion, and learning — on a graph that evolves with every session.\n\nRead the full paper: [Introducing Recursive Memory Harness](https://orimnemos.com/rmh)\n\n---\n\n## What It Does\n\n- **Persistent identity.** Agent state — name, personality, goals, methodology — is stored in plain markdown and auto-injected at session start via MCP instructions. Identity survives client switches, machine migrations, and model changes without reconfiguration.\n\n- **Knowledge graph.** Every `[[wiki-link]]` is a directed edge. PageRank authority, Louvain community detection, betweenness centrality, bridge detection, orphan and dangling link analysis. Structure is queryable through MCP tools and CLI.\n\n- **Three memory spaces.** Identity (`self/`) decays at 0.1x — barely fades. Knowledge (`notes/`) decays at 1.0x — lives and dies by relevance. Operations (`ops/`) decays at 3.0x — burns hot and clears itself. The separation is architectural, not cosmetic.\n\n- **Cognitive forgetting.** Notes decay using ACT-R base-level learning equations, not arbitrary TTLs. Used notes stay alive. Their neighbors stay warm through spreading activation along wiki-link edges. Structurally critical nodes are protected by Tarjan's algorithm. `ori prune` analyzes the full activation topology before archiving anything.\n\n- **Four-signal fusion.** Semantic embeddings, BM25 keyword matching, personalized PageRank, and associative warmth fused through score-weighted Reciprocal Rank Fusion. Intent classification (episodic, procedural, semantic, decision) shifts signal weights automatically.\n\n- **Dampening pipeline.** Three post-fusion stages validated by ablation testing: gravity dampening halves cosine-similarity ghosts with zero query-term overlap, hub dampening applies a P90 degree penalty to prevent map notes from dominating results, and resolution boost surfaces actionable knowledge (decisions, learnings) over passive observation.\n\n- **Learning retrieval (v0.4.0).** Three intelligence layers improve retrieval quality from session to session, synthesized from 63 research sources. See [Retrieval Intelligence](#retrieval-intelligence-v040) below.\n\n- **Capture-promote pipeline.** `ori add` captures to inbox. `ori promote` classifies (idea, decision, learning, insight, blocker, opportunity), detects links, suggests areas. 50+ heuristic patterns. Optional LLM enhancement.\n\n- **Zero cloud dependencies.** Local embeddings via all-MiniLM-L6-v2 running in-process. SQLite for vectors and intelligence state. Everything on your filesystem. Zero API keys required for core functionality.\n\n---\n\n## Retrieval Intelligence (v0.4.0)\n\nThree learning layers that improve retrieval quality over time without manual tuning. Synthesized from 63 research sources across reinforcement learning, information retrieval, cognitive science, and bandit theory.\n\n### Layer 1 — Q-Value Reranking\n\nNotes earn Q-values from session outcomes via exponential moving average updates. Over time, genuinely useful notes rise and noise sinks.\n\n| Signal | Reward | What triggers it |\n|--------|--------|-----------------|\n| Forward citation | +1.0 | You `[[link]]` a retrieved note in new content |\n| Update after retrieval | +0.5 | You edit a note you just retrieved |\n| Downstream creation | +0.6 | You create a new note after retrieving |\n| Within-session re-recall | +0.4 | Same note surfaces across different queries |\n| Dead end (top-3, no follow-up) | −0.15 | Retrieved in top 3 but nothing follows |\n\nAfter RRF fusion, Phase B reranks the candidate set with a lambda blend of similarity score and learned Q-value, plus a UCB-Tuned exploration bonus that ensures under-retrieved notes still get discovered. Exposure-aware correction prevents the same notes from dominating every session. A cumulative bias cap (MAX=3.0, compression=0.3) prevents runaway score inflation.\n\n### Layer 2 — Co-Occurrence Edges\n\nNotes that are retrieved together grow edges between them — Hebbian learning on the knowledge graph. Edge weights are computed using NPMI normalization (genuine association beyond base rate), GloVe power-law frequency scaling, and Ebbinghaus decay with strength accumulation (frequently co-retrieved pairs decay slower).\n\nPer-node Turrigiano homeostasis prevents hub notes from absorbing all edge weight. Bibliographic coupling bootstraps day-0 edges from existing wiki-link structure before any queries have been run.\n\nThe combined wiki-link + co-occurrence graph feeds a Personalized PageRank walk (HippoRAG, α=0.5) that surfaces notes semantic search alone would never find.\n\n### Layer 3 — Stage Meta-Learning\n\nEach pipeline stage (BM25, PageRank, warmth, hub dampening, Q-reranking, co-occurrence PPR) is wrapped in a LinUCB contextual bandit with an 8-dimensional query feature vector. The system learns which stages help for which query types and auto-skips stages that consistently hurt.\n\nThree-way decisions per stage: **run** / **skip** / **abstain** (stop the pipeline early). Cost-sensitive thresholds ensure expensive stages face a higher bar. Essential stages (semantic search, RRF fusion) never skip. An ACQO two-phase curriculum runs all stages during exploration (first 50 samples), then optimizes.\n\n### Session Learning Loop\n\n```\nQuery → Retrieve → Use (cite, update, create) → Reward signals\n  ↓                                                    ↓\n  Co-occurrence edges grow                Q-values update (session-end batch)\n  ↓                                                    ↓\n  Stage meta-learner updates              Better retrieval next session\n```\n\nAll updates happen in a single SQLite transaction at session end, in order: co-occurrence → Q-values → stage learning.\n\n---\n\n## The Stack\n\n```\nLayer 6: MCP Server                    16 tools, 5 resources — any agent talks to this\nLayer 5: Recursive Exploration         PPR graph traversal, sub-question decomposition, convergence detection\nLayer 4: Retrieval Intelligence        Q-value reranking, co-occurrence learning, stage meta-optimization\nLayer 3: Dampening Pipeline            gravity, hub, resolution — ablation-validated\nLayer 2: Four-Signal Fusion            semantic + BM25 + PageRank + warmth → score-weighted RRF\nLayer 1: Knowledge Graph + Vitality    wiki-links, ACT-R decay, spreading activation, zone classification\nLayer 0: Markdown files on disk        git-friendly, human-readable, portable\n```\n\n16 MCP tools · 5 resources · 17 CLI commands · 579 tests\n\n---\n\n## Token Economics\n\nWithout retrieval, every question requires dumping the entire vault into context. With Ori, the cost stays flat.\n\n| Vault Size | Without Ori | With Ori | Savings |\n|:----------:|:-----------:|:--------:|:-------:|\n| 50 notes | 10,100 tokens | 850 tokens | **91%** |\n| 200 notes | 40,400 tokens | 850 tokens | **98%** |\n| 1,000 notes | 202,000 tokens | 850 tokens | **99.6%** |\n| 5,000 notes | 1,010,000 tokens | 850 tokens | **99.9%** |\n\nA typical session costs **~$0.10** with Ori. Without it: **~$6.00+**.\n\n---\n\n## Architecture\n\n```\n                          Any MCP Client\n                    (Claude, Cursor, Windsurf,\n                     Cline, Hermes, custom agents, VPS)\n                              │\n                        MCP Protocol\n                        (stdio / JSON-RPC)\n                              │\n                    ┌───────────────────┐\n                    │    Ori MCP Server  │\n                    │                   │\n                    │  instructions     │   identity auto-injected\n                    │  resources  (5)   │   ori:// endpoints\n                    │  tools    (16)    │   full memory operations\n                    └─────────┬─────────┘\n                              │\n            ┌─────────────────┼─────────────────┐\n            │                 │                 │\n      ┌───────────┐    ┌───────────┐    ┌───────────┐\n      │ Knowledge │    │ Identity  │    │Operations │\n      │   Graph   │    │  Layer    │    │  Layer    │\n      │           │    │           │    │           │\n      │  notes/   │    │  self/    │    │  ops/     │\n      │  inbox/   │    │  identity │    │  daily    │\n      │  templates│    │  goals    │    │  reminders│\n      └─────┬─────┘    │  method.  │    │  sessions │\n            │          └───────────┘    └───────────┘\n      ┌─────┴──────┐\n      │            │\n   Wiki-link   Embedding        ┌──────────────────────┐\n    Graph       Index            │ Retrieval Intelligence│\n   (in-mem)    (SQLite)          │                      │\n      │            │             │  Q-values  (note_q)  │\n   PageRank    Semantic          │  Co-occur  (edges)   │\n   Spreading   BM25              │  Stage Q   (LinUCB)  │\n   Activation  4-Signal          │  Dampening (3 stages)│\n   Communities Fusion            │  Explore   (PPR+RMH) │\n                                 └──────────────────────┘\n```\n\n---\n\n## MCP Tools\n\n| Tool | What it does |\n|------|-------------|\n| `ori_orient` | Session briefing: daily status, goals, reminders, vault health, index freshness |\n| `ori_update` | Write to identity, goals, methodology, daily, or reminders |\n| `ori_status` | Vault overview |\n| `ori_health` | Full diagnostics |\n| `ori_add` | Capture to inbox |\n| `ori_promote` | Promote with classification, linking, and area assignment |\n| `ori_validate` | Schema validation |\n| `ori_query` | Graph queries: orphans, dangling, backlinks, cross-project |\n| `ori_query_ranked` | Full retrieval with Q-value reranking, co-occurrence PPR, and stage meta-learning |\n| `ori_warmth` | Inspect the associative warmth field |\n| `ori_query_similar` | Semantic search (vector only, faster) |\n| `ori_query_important` | PageRank authority ranking |\n| `ori_query_fading` | Vitality-based decay detection |\n| `ori_explore` | Recursive graph traversal — PPR, sub-question decomposition, convergence detection |\n| `ori_prune` | Activation topology analysis and archive candidates |\n| `ori_index_build` | Build/update embedding index and bootstrap co-occurrence edges |\n\n---\n\n## CLI\n\n```bash\n# Vault management\nori init [dir]                    # Scaffold a new vault\nori status                        # Vault overview\nori health                        # Full diagnostics\n\n# Note lifecycle\nori add <title> [--type <type>]   # Capture to inbox\nori promote [note] [--all]        # Promote to knowledge graph\nori validate <path>               # Schema validation\nori archive [--dry-run]           # Archive stale notes\nori prune [--apply] [--verbose]   # Topology analysis + archive candidates\n\n# Retrieval\nori explore <query>               # Recursive graph traversal (RMH)\nori query ranked <query>          # Full intelligent retrieval\nori query similar <query>         # Semantic search\nori query important               # PageRank ranking\nori query fading                  # Vitality detection\nori query orphans                 # Notes with no incoming links\nori query dangling                # Broken wiki-links\nori query backlinks <note>        # What links to this note\nori query cross-project           # Multi-project notes\n\n# Infrastructure\nori index build [--force]         # Build embedding index\nori index status                  # Index statistics\nori graph metrics                 # PageRank, centrality\nori graph communities             # Louvain clustering\nori serve --mcp [--vault <path>]                                # Run MCP server\nori bridge claude-code [--scope <s>] [--activation <a>] [--vault <p>]  # Claude Code (hooks + MCP + instructions)\nori bridge hermes [--scope <s>] [--activation <a>] [--vault <p>]       # Hermes Agent (plugin + MCP + instructions)\nori bridge opencode [--scope <s>] [--activation <a>] [--vault <p>]     # OpenCode (plugin + MCP + AGENTS.md)\nori bridge cursor [--scope <s>] [--vault <p>]                          # Cursor (MCP config)\nori bridge codex [--scope <s>] [--vault <p>]                           # Codex (TOML config)\nori bridge generic [--scope <s>] [--vault <p>] [--json]                # Any MCP client (prints config)\nori bridge status [--json]                                             # Inspect all bridge installs\nori bridge <target> --uninstall                                        # Remove Ori config for a target\n```\n\nPath-taking commands treat relative file paths as vault-relative. Absolute\npaths continue to work unchanged.\n\n---\n\n## Vault Structure\n\n```\nvault/\n├── .ori                       # Vault marker\n├── ori.config.yaml            # Configuration\n├── notes/                     # Knowledge graph (flat, no subfolders)\n│   └── index.md               # Hub entry point\n├── inbox/                     # Capture buffer\n├── templates/                 # Note and map schemas\n├── self/                      # Agent identity\n│   ├── identity.md            # Name, personality, values\n│   ├── goals.md               # Active threads, priorities\n│   ├── methodology.md         # Processing principles\n│   └── memory/                # Agent's accumulated insights\n└── ops/                       # Operational state\n    ├── daily.md               # Today's completed and pending\n    ├── reminders.md           # Time-bound commitments\n    └── sessions/              # Session logs\n```\n\nEvery file is plain markdown. Open it in any text editor, Obsidian, or your file browser. `git log` is your audit trail.\n\n---\n\n## Deployment\n\n**Local.** Install globally, `ori init`, connect your MCP client. Done.\n\n**VPS / headless.** Install on the server. `ori serve --mcp --vault /path/to/vault`. Memory persists on the filesystem. Back up with `git push`.\n\n**Remote terminals.** Hermes Agent supports Docker, SSH, Modal, and Daytona backends. If your agent runs in a remote terminal, `ori` must be installed and on PATH inside that environment, and the vault must be on persistent storage (not ephemeral). For serverless backends like Modal where environments hibernate, mount the vault on a persistent volume.\n\n**Multi-vault.** Separate Ori instances for separate agents. Each vault is self-contained: its own identity, knowledge graph, and operational state.\n\n**Scriptable.** CLI returns structured JSON. Use in cron jobs, webhook handlers, or orchestration loops.\n\n## Install Model\n\nOri separates three install concepts:\n\n- `scope`: `global` follows one vault across the machine, `project` stays inside one repo/workspace\n- `activation`: `auto` runs `ori_orient` at session start where the adapter supports it, `manual` leaves tools available but does not auto-orient\n- `vault`: explicit `--vault` wins; otherwise Ori resolves by install scope\n\nPrecedence rules:\n\n- project install overrides global install\n- explicit `--vault` overrides inferred vault\n- project activation overrides global activation\n\nBridge lifecycle:\n\n- rerun the same `ori bridge ...` command to update vault path or activation in place\n- use `--uninstall` to remove Ori-owned config from supported adapters\n- generic installs emit manual uninstall instructions because Ori does not own that client config surface\n\nClaude Code, Hermes Agent, and OpenCode are fully automated adapters with lifecycle hooks. Claude Code uses hook scripts; Hermes uses a native Python plugin installed at `~/.hermes/plugins/ori/`; OpenCode uses a JavaScript plugin at `.opencode/plugins/lifecycle.js`. All three auto-orient at session start (via first-run detection) and capture insights at session idle. Cursor and Codex have native MCP config install support. Codex writes to `~/.codex/config.toml` and uses a single global config surface; \"project\" scope there means project-like runtime vault discovery, not a separate project config file. Other MCP-capable clients can use `ori bridge generic` now and wire the emitted config into their own client surface.\n\n---\n\n## Configuration\n\n`ori.config.yaml` controls all tunable parameters. Generated with sensible defaults on `ori init`.\n\n| Section | Controls |\n|---------|----------|\n| `vitality` | Decay parameters, metabolic rates, zone thresholds, bridge bonus |\n| `activation` | Spreading activation: damping, max hops, min boost |\n| `retrieval` | Signal weights, exploration budget, RRF k |\n| `engine` | Embedding model, database path |\n| `warmth` | Surprise threshold, PPR parameters, graph weight |\n| `promote` | Auto-promotion, project routing |\n| `llm` | Optional: Anthropic, OpenAI-compatible, or local models |\n\nLLM integration is optional. Every operation works deterministically with heuristics alone. When configured, LLM improves classification and link suggestions.\n\n---\n\n## Why Sovereignty Matters\n\nMost memory systems store your agent's knowledge in infrastructure you do not control. A proprietary database. A cloud service. A vendor's format.\n\nOri stores memory as files you own. The vault is portable. Move it to a new machine, push it to a git remote, open it in a text editor. Switch MCP clients by changing one config line. The memory survives any platform change because it was never locked to a platform.\n\nThis is not ideological. It is architectural. Portable memory is composable memory.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/aayoawoyemi/Ori-Mnemos.git\ncd Ori-Mnemos\nnpm install\nnpm run build\nnpm link\nori --version\n```\n\n```bash\nnpm test              # 579+ tests\nnpm run lint          # Type check\nnpm run dev           # Watch mode\n```\n\nThanks to [@maichler](https://github.com/maichler) and the rest of the Ori community for their PRs and additions.\n\n---\n\n## License\n\nApache-2.0\n\n---\n\nMemory is sovereignty. Ori gives your agent a mind.\n",
  "bytes": 24588,
  "sha": "5fe080b05fda24d1e28097ffc2f28a4d4471a667b0f0adea33d86489fea04efc",
  "repo_slug": "aayoawoyemi/ori-mnemos",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aayoawoyemi_ori_memory_88ae2dea/readme"
}