Memorius — Universal memory vault for any AI agent

Built for the way agents actually work

Drop-in memory that any AI agent can use. No lock-in, no per-agent rewrites — one vault, many frontends.

Drop-in for any MCP client

Point any MCP-compatible client at memorius serve and instantly get memory, semantic search, and diary tools. No SDK to embed.

Hierarchical knowledge

Organize memory with a Vault → Shelf → Folder → Note hierarchy. Mine conversation transcripts into structured memories automatically.

Pluggable embeddings

ChromaDB default with bundled ONNX, sentence-transformers for higher quality, or OpenAI for production. Swap with one config change.

7 agent integrations

Claude Code, Codex CLI, Gemini CLI, OpenCode, Pi, OpenClaude, OpenClaw — auto-detected from hook payloads, no config needed.

REST API included

FastAPI HTTP server for any non-MCP client. GET /health, POST /store, POST /search, and more.

Obsidian integration

Bidirectional sync with Obsidian vaults. YAML frontmatter is parsed, folder hierarchy preserved. memorius obsidian import/export.

Up and running in 30 seconds

Install, initialize, store, search. That's it.

# Install
pip install memorius

# Initialize a vault
memorius init

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

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

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

# Write a diary entry
memorius diary --session "session-001" --title "Research findings"

# Check vault status
memorius status

From zero to persistent memory

No cloud account, no API keys, no setup ceremony. Just install and go.

01 Install the package — one pip command, no heavy dependencies beyond ChromaDB.
02 Initialize a vault — creates the storage directory and config at ~/.memorius/.
03 Store your first memory with memorius store — automatic embedding and hierarchical tagging.
04 Find anything later with semantic search — relevance-ranked results from ChromaDB vector store.

Architecture

A single Python package, four entry points, two storage backends.

┌────────────────────────────────────────────────────────────┐
│                       Memorius                             │
├────────────────────────────────────────────────────────────┤
│  CLI        memorius init | store | search | mine | ...    │
│  MCP        JSON-RPC protocol server (stdin/stdout)        │
│  REST       FastAPI HTTP server (optional)                 │
│  Hooks      Auto-detect: Claude Code, Codex, Gemini, ...   │
│  Obsidian   Import / export notes from Obsidian vaults     │
├────────────────────────────────────────────────────────────┤
│  Vault Engine                                              │
│  ├── ChromaStore    Vector search (ChromaDB)               │
│  ├── SQLiteStore    Metadata & hierarchy (SQLite)          │
│  └── Embeddings     Pluggable providers (ONNX / SF / OA)   │
├────────────────────────────────────────────────────────────┤
│  Vault  >  Shelf  >  Folder  >  Note  hierarchy           │
│  Diaries          Session diary entries                    │
│  Mine             Extract memories from transcripts        │
├────────────────────────────────────────────────────────────┤
│  Plugin Gen    →  Generate per-agent plugins               │
│  Normalizers   →  Import Discord/Telegram/WhatsApp/etc     │
│  Obsidian      →  Bidirectional vault sync                 │
└────────────────────────────────────────────────────────────┘

Vault engine is the single source of truth — CLI, MCP, REST, and hooks all route through it.
ChromaDB handles vector search; SQLite handles metadata and the hierarchy.
Embeddings are swappable: bundled ONNX (default, no extra deps), sentence-transformers, or OpenAI.
Hooks auto-detect which agent sent the event from the JSON payload — no --agent flag required.
Plugin generator writes per-agent plugin files from one universal manifest.

Works with the agents you already use

Hooks are auto-detected from the event payload — pipe JSON in, get memories out. No per-agent config to maintain.

Claude Code

Anthropic — stop, precompact

Codex CLI

OpenAI — session_start, stop

Gemini CLI

Google — stop, session_start

OpenCode

anomalyco/sst — stop, precompact

kachow-compatible — tool_call, turn_end

OpenClaude

stop, precompact

OpenClaw

openclaw marker — session_start

Detection priority: OpenClaude → Claude Code → Codex → Gemini CLI → OpenClaw → OpenCode → Pi → Generic.

CLI reference

Every command you'll need on day one. Full reference in the README.

Core

memorius initInitialize a new vault

memorius statusShow vault status

memorius store <text>Store a memory

memorius search <q>Semantic search

memorius mine <file>Extract memories from transcript

memorius lsBrowse vault hierarchy

Diaries

memorius diary <session>Write a diary entry

memorius diariesList recent entries

Servers

memorius serveStart MCP server (stdio)

memorius serve-restStart REST API server

Obsidian

memorius obsidian listExplore vault structure

memorius obsidian importImport notes as memories

memorius obsidian exportExport memories as notes