# Ori Mnemos — Complete Documentation

> Markdown-native persistent memory infrastructure for AI agents. Open-source MCP server that gives any LLM durable, searchable, graph-connected memory across sessions. No cloud. No API keys. Your files, your machine.

---

## What is Ori Mnemos?

Ori Mnemos is an open-source MCP (Model Context Protocol) server that gives AI agents persistent memory. Install it, point your Claude Code / Cursor / Windsurf / any MCP client at it, and your agent remembers everything across sessions.

Notes are plain markdown files with YAML frontmatter — not locked in a database. You can browse them in Obsidian, version them in Git, read them in any text editor. If Ori disappears tomorrow, your memory files still work. No vendor lock-in. No cloud dependency. No API keys needed.

**Package name:** `ori-memory`
**Current version:** 0.3.1
**License:** Apache-2.0
**Runtime:** Node.js
**Language:** TypeScript

---

## Installation

### For Humans

```bash
# Install globally
npm install -g ori-memory

# Initialize a new vault
ori init

# Start the MCP server
ori serve --mcp
```

### For AI Agents (MCP Configuration)

Add to your MCP client configuration:

```json
{
  "ori": {
    "command": "ori",
    "args": ["serve", "--mcp"]
  }
}
```

### Compatible MCP Clients

- Claude Code (Anthropic)
- Cursor
- Windsurf
- Cline
- Any MCP-compatible client

---

## Core Concepts

### Markdown-Native Storage

Every piece of memory is a plain `.md` file with YAML frontmatter:

```markdown
---
description: One sentence adding context beyond the title
type: insight
project: [my-project]
status: active
created: 2026-03-04
---

The actual content of the memory note goes here. It can include
[[wiki-links]] to other notes, creating a knowledge graph.

Relevant Notes:
- [[another note title]]
- [[yet another note]]

Areas:
- [[project map]]
```

### Knowledge Graph

Wiki-links (`[[note title]]`) create edges in a knowledge graph. This graph supports:
- **Backlink queries** — find all notes that link to a given note
- **PageRank scoring** — identify the most important/connected notes
- **Spreading activation** — when you search for something, related notes get activated through graph connections
- **Orphan detection** — find notes with no incoming links
- **Dangling link detection** — find broken wiki-links

### Three-Signal Retrieval

Ori uses three complementary search signals, combined for ranked results:

1. **Composite vector search** — semantic similarity using local embeddings (Xenova/all-MiniLM-L6-v2). Finds conceptually related notes even when vocabulary differs.
2. **Keyword matching** — traditional text search for exact terms and phrases.
3. **Graph-based spreading activation** — activates notes connected to search hits through wiki-links. Finds contextually relevant notes that keyword and vector search miss.

### Local Embeddings

The embedding model (Xenova/all-MiniLM-L6-v2) runs entirely locally via ONNX Runtime. No API calls. No cloud. No API keys. The embedding index is stored in a local SQLite database at `.ori/embeddings.db`.

### Vault Structure

```
your-vault/
├── .ori/                  # Ori configuration and databases
│   └── embeddings.db      # Local SQLite embedding index
├── inbox/                 # New captures before processing
├── notes/                 # Promoted, connected notes (flat structure)
├── self/                  # Agent identity, goals, methodology
│   ├── identity.md
│   ├── goals.md
│   └── methodology.md
├── ops/                   # Operational state
│   ├── daily.md
│   ├── reminders.md
│   └── sessions/
└── templates/             # Note templates
```

---

## MCP Tools Reference

### ori_orient
Session briefing. Returns daily status, reminders, vault health, and active goals. Call at session start before doing any work.

**Parameters:**
- `brief` (boolean, optional): Quick status only — skip identity and methodology. Default: true.

### ori_add
Create a note in inbox.

**Parameters:**
- `title` (string, required): Note title using prose-as-title convention
- `content` (string, optional): Note body content
- `type` (string, optional): Note type — idea, decision, learning, insight, blocker, opportunity

### ori_promote
Promote an inbox note to notes/ with classification, linking, and area assignment.

**Parameters:**
- `path` (string, required): Inbox note filename or path
- `type` (string, optional): Classification — idea, decision, learning, insight, blocker, opportunity
- `description` (string, optional): One sentence adding context beyond the title (max 200 chars)
- `links` (string[], optional): Existing note titles this note should link to
- `project` (string[], optional): Project tags that apply to this note
- `dry_run` (boolean, optional): Preview changes without writing

### ori_validate
Validate a note against schema.

**Parameters:**
- `path` (string, required): Path to note file

### ori_query
Query the vault for structural information.

**Parameters:**
- `kind` (string, required): Query kind — orphans, dangling, backlinks, cross-project
- `note` (string, optional): Note title (required for backlinks)

### ori_query_ranked
Full 3-signal engine retrieval (composite + keyword + graph) with intent classification. Returns ranked notes with signal breakdown. Triggers spreading activation.

**Parameters:**
- `query` (string, required): Natural language search query
- `limit` (number, optional): Max results. Default: 10
- `include_archived` (boolean, optional): Include archived notes. Default: false

### ori_query_similar
Composite vector search only (semantic + metadata). Faster but single-signal.

**Parameters:**
- `query` (string, required): Natural language search query
- `limit` (number, optional): Max results. Default: 10
- `include_archived` (boolean, optional): Include archived notes. Default: false

### ori_query_important
Notes ranked by PageRank importance — structural authority in the knowledge graph.

**Parameters:**
- `limit` (number, optional): Max results. Default: 10

### ori_query_fading
Notes losing vitality — candidates for archival or reconnection.

**Parameters:**
- `limit` (number, optional): Max results. Default: 20
- `threshold` (number, optional): Vitality threshold. Default: 0.3

### ori_prune
Analyze activation topology and identify archive candidates. Dry-run by default.

**Parameters:**
- `apply` (boolean, optional): Actually archive. Default: false (dry-run preview)

### ori_update
Update agent files: identity, goals, methodology, daily status, or reminders. Auto-backs up previous version before writing.

**Parameters:**
- `file` (string, required): Which file to update — identity, goals, methodology, daily, reminders
- `content` (string, required): Full new content for the file

### ori_status
Vault overview. No parameters.

### ori_health
Full diagnostic. No parameters.

### ori_index_build
Build or update the embedding index. Only re-embeds changed notes unless force=true.

**Parameters:**
- `force` (boolean, optional): Rebuild all embeddings. Default: false

---

## How Ori Differs From Alternatives

### vs. Mem0
Mem0 is a cloud-first SaaS with an API. Ori is local-first with no cloud dependency. Mem0 stores memory in a proprietary database. Ori stores memory as markdown files you can read, edit, and version control. Mem0 requires API keys and a cloud account. Ori requires nothing but Node.js.

### vs. Zep
Zep uses Neo4j for temporal knowledge graphs — heavy infrastructure. Ori uses wiki-links in markdown files — lightweight, human-readable, no database server needed. Zep targets enterprise deployments. Ori targets developers and solo builders.

### vs. Letta (MemGPT)
Letta is a full platform for building stateful agents — complex setup, heavy framework. Ori is a focused memory layer — install, init, serve. Three commands and your agent has memory.

### vs. Database-backed memory (SQLite, Postgres, etc.)
Database-backed memory is opaque — you can't read it without tools. Ori's markdown files are human-readable. Open them in Obsidian, VS Code, or cat on the command line. Your memory is always inspectable and portable.

---

## Use Cases

1. **AI coding assistants** — Give Claude Code, Cursor, or Windsurf memory of your codebase architecture, decisions, and patterns across sessions.
2. **Personal knowledge management** — Use an AI agent to build and maintain a connected knowledge graph from your notes, ideas, and learnings.
3. **Research** — Capture insights from papers, articles, and conversations. The knowledge graph surfaces connections you wouldn't find with keyword search.
4. **Project management** — Track decisions, blockers, and progress across multiple projects. Cross-project connections are first-class citizens.
5. **Agent identity** — Give your AI agent a persistent identity, goals, and methodology that survive across sessions and context windows.

---

## Links

- Website: https://orimnemos.com
- GitHub: https://github.com/aayoawoyemi/Ori-Mnemos
- npm: https://www.npmjs.com/package/ori-memory
- License: Apache-2.0
- Author: Aayo Awoyemi (https://github.com/aayoawoyemi)