Ori Mnemos

Open-source persistent memory infrastructure for AI agents.

Ori 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.

Persistent memory across sessions, clients, and machines. Zero-infrastructure retrieval that matches and in several cases strongly outperforms incumbents on 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.

v0.7.0 · npm · Paper · Apache-2.0

Benchmarks

HotpotQA — Multi-Hop Retrieval

Head-to-head against Mem0. Both systems indexed the same documents and answered the same questions in the same run.

n = 50, single run, no seed averaging, topK = 5. Mem0 at 1.0.6 (March 2026); 2.x is not yet re-run, so read this as a point-in-time comparison, not a current one. Raw output: bench/results/, reproduce with bench/hotpotqa-eval.ts and bench/mem0-hotpotqa.py.

Latency is not reported here. The evaluation harness does not record it, so any number would be recalled rather than measured. What is measured is that Ori answers from markdown plus a local SQLite index with no API key and no network.

LoCoMo — Long-Term Conversational Memory

695 questions over 10 conversations, GPT-4.1-mini for answer generation, BM25 + embedding + PageRank fusion for retrieval.

Temporal is the weak category and is reported as such. Raw output: bench/results/locomo-eval-2026-03-20T06-16-41-585Z.json.

No comparison table against published LoCoMo leaderboards is given, on purpose. Those numbers are an LLM-judge score; the above is answer F1. They are different quantities and putting them in one column would invent a ranking rather than report one. A previous version of this README did exactly that.

LoCoMo itself also has known defects — 6.4% of questions carry wrong answer keys, and the standard judge accepts a majority of wrong answers — so a close result on it is weak evidence in either direction.

Quick Start

npm install -g ori-memory
ori init my-agent
cd my-agent

Connect to your agent:

# Full adapters — auto-orient at session start, capture at session end
ori bridge claude-code --vault ~/brain                 # hooks + MCP + CLAUDE.md
ori bridge hermes --vault ~/brain                      # native plugin + MCP + HERMES.md
ori bridge opencode --vault ~/brain                    # plugin + MCP + AGENTS.md

# MCP-only adapters — tools available, no lifecycle automation
ori bridge cursor --vault ~/brain                      # .cursor/mcp.json
ori bridge codex --vault ~/brain                       # ~/.codex/config.toml

# Any MCP client
ori bridge generic --vault ~/brain                     # prints config for manual setup

Claude 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.

Manual MCP config (works with any client that speaks MCP):

{
  "mcpServers": {
    "ori": {
      "command": "ori",
      "args": ["serve", "--mcp", "--vault", "/path/to/brain"],
      "env": { "ORI_VAULT": "/path/to/brain" }
    }
  }
}

Start a session. The agent receives its identity automatically and begins onboarding on first run.

What's New

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.

$ ori explore-start "why did we choose SQLite over postgres"

exploration e7f2 — 3 branches
├─ [1] storage engine tradeoffs        4 notes, strong signal
├─ [2] deployment constraints          2 notes
└─ [3] prior migration decisions       dead end — no notes

next: ori explore-expand e7f2 1   |   ori explore-conclude e7f2 --answered

v0.5.6 — OpenCode bridge. Full lifecycle integration: first-run onboarding, auto session capture, note validation, multi-vault support. ori bridge opencode — one command.

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.

Full history in the CHANGELOG.

Recursive Memory Harness

Ori is the first implementation of the Recursive Memory Harness (RMH) framework — a set of constraints on how persistent memory should behave for AI agents.

The core insight comes from Recursive Language Models (Zhang, Krassa & Khattab, 2026). 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.

Three constraints define the framework:

1. 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.

2. 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.

3. 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.

Most memory systems treat retrieval as search. RMH treats retrieval as navigation, recursion, and learning — on a graph that evolves with every session.

Read the full paper: Introducing Recursive Memory Harness

What It Does

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• Learning retrieval (v0.4.0). Three intelligence layers improve retrieval quality from session to session, synthesized from 63 research sources. See Retrieval Intelligence below.

• 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.

• 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.

Retrieval Intelligence (v0.4.0)