memorius MCP server

Memorius

---

Persistent, searchable memory with hierarchy, semantic retrieval, knowledge graphs, and MCP-native integration — for Claude Code, Codex CLI, Gemini CLI, OpenClaude, OpenCode, Pi, OpenClaw, and any MCP-compatible agent.

📚 Documentation: https://dream-pixels-forge.github.io/memorius/ — CLI reference, MCP server, hooks, REST API, architecture, and the memory engine.

Found this useful? Leave a star ⭐ — it's the best way to support the project.

---

What Memorius gives you

🧠 Hierarchical vault	Vault → Shelf → Folder → Note. Organize memory like a library, not a flat bucket.
🔍 Semantic search	Vector similarity with cross-encoder reranking and temporal-decay ranking.
🕸️ Knowledge graph	Entity co-occurrence graph with path-finding and relation extraction.
🔌 MCP + REST servers	memorius serve (stdio MCP) and memorius serve-rest (FastAPI, TLS, auth).
🪝 Agent hooks	Auto-detecting lifecycle hooks for 7+ AI coding agents — normalizers + security.
📖 3D bookcase	Walkable first-person vault browser (memorius bookcase) with librarian hippo.
🔄 Consolidation	Neuroscience-inspired decay, pruning, and fact-checking to keep memory fresh.
🔒 No lock-in	Local-first, ChromaDB + SQLite-vec backends, no cloud, no required API keys.

---

Install

pip install memorius

All features — vector search, cross-encoder reranker, REST API server, SQLite-vec backend, OpenAI embeddings, knowledge graph, agent hooks — are included out of the box. No extra install flags needed.

Verify:

memorius --version
memorius init          # creates ~/.memorius/config.yaml + storage dir

---

Run in a container

The production image is multi-stage, runs as non-root UID 10001, and uses dumb-init as PID 1, with the vault on a volume at /data.

docker build -t memorius:prod .
docker run --rm -p 127.0.0.1:8912:8912 -v memorius-data:/data memorius:prod

Or with Compose:

docker compose up --build

The REST API is published on loopback only; without MEMORIUS_API_KEY it is read-only for non-loopback clients. Inside the container the API is plaintext (--insecure) — terminate TLS in front of it or mount certificates and override the command. Liveness: GET /health/live.

---

Quick start

# 1. Initialize a vault
memorius init

# 2. Store a memory
memorius store "The sky is blue because Rayleigh scattering scatters shorter wavelengths more" \
  --vault main --shelf science --folder physics

# 3. Semantic search
memorius search "why is the sky blue"

# 4. Mine memories from a conversation
memorius mine transcript.txt --vault conversations

# 5. Check vault status
memorius status

That's the whole loop: store → embed → search. Read the Getting Started guide for the vault hierarchy, agent skill, and a recommended first-week flow.

---

CLI at a glance

memorius store "text"       [--vault/--shelf/--folder/--note/--ttl]
memorius search "query"     [--n/--expand-graph/--rerank/--web/--tag]
memorius mine file.txt      [--vault/--text]
memorius extract file.txt   [--backend openai|ollama|regex]
memorius diary "session"    [--title/--summary]
memorius ls [vault]
memorius consolidate        [--threshold/--dry-run]
memorius factcheck "stmt"   [--web]
memorius profile "session"
memorius prune              [--threshold/--dry-run/--delete]
memorius graph              [view|export-html|stats|json]
memorius learn "text"       --category bug_fix
memorius recall "query"
memorius obsidian           [list|import|export]
memorius export ./backup    [--format json|markdown]
memorius import ./backup.json [--replace]
memorius doctor             # 6 health checks
memorius repair             [--reindex/--dry-run]
memorius stats [--json]     # vault + memory + graph + doctor summary
memorius status [--json]    # vault + embeddings + recent diaries
memorius serve              # MCP server (stdio)
memorius serve-rest         [--daemon/--stop]  # FastAPI server
memorius bookcase           # 3D walkable vault browser

---

Vault Bookcase (3D walkable)

Run the bookcase:

memorius bookcase

It starts the REST API on http://127.0.0.1:8912, serves the bookcase page on http://127.0.0.1:8400/bookcase.html, and opens your browser. Everything is loopback-only — nothing leaves your machine.

Walk: WASD or arrow keys · Shift to hurry · Click to grab mouse-look · / to ask the librarian · M for floor plan · ? for all controls.

---

Documentation

The full docs live on the site — each concern on its own page:

Page	What's on it
Getting Started	Install, init, first memory, Vault→Shelf→Folder→Note hierarchy, agent skill
CLI Reference	Every subcommand and flag (incl. repair and --json)
MCP Server	All 29 tools + per-agent client config snippets
Agent Hooks	Auto-detecting lifecycle hooks, 10 actions, normalizers, security
REST API	Full endpoint table, auth, rate limits, daemon mode, TLS
Architecture	Search pipeline, embeddings, vector backends, graph, configuration
Agent Compatibility	Which agents, detection priority, how to plug in your own
Memory Engine	Decay, consolidation, pruning, fact-checking, reranking, doctor, repair

---

License & support

MIT · Full release history in CHANGELOG.md.

Built by Dream-Pixels-Forge. Open source.