# Memorius > Memorius is a self-contained, agent-agnostic memory system that gives LLMs and AI agents persistent, searchable memory with a hierarchical knowledge organization. Drop-in with multi-backend vector storage, pluggable embeddings, built-in MCP + REST servers, and auto-detecting agent hooks for 7 different AI coding agents. - **Type:** MCP server - **Install:** `agentstack add mcp-dream-pixels-forge-memorius` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Dream-Pixels-Forge](https://agentstack.voostack.com/s/dream-pixels-forge) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Dream-Pixels-Forge](https://github.com/Dream-Pixels-Forge) - **Source:** https://github.com/Dream-Pixels-Forge/memorius - **Website:** https://dream-pixels-forge.github.io/memorius/ ## Install ```sh agentstack add mcp-dream-pixels-forge-memorius ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Memorius Universal memory vault for any AI agent. > 🧠 **Works with Claude Code, Codex CLI, Gemini CLI, OpenClaude, OpenCode, Pi, and any MCP-compatible agent.** > > 🌐 **Landing page:** https://dream-pixels-forge.github.io/memorius/ > > If you find this project useful, leaving a star ⭐ on the repository is the best way to support my work! ## Why Memorius? Most AI memory tools lock you into one agent ecosystem. Memorius is **agent-agnostic by design** — the same memory vault works whether you use Claude Code, Codex CLI, Gemini CLI, or any MCP-compatible agent. No vendor lock-in. | Feature | Memorius | Others | |---------|----------|--------| | Agent support | **7 agents** (auto-detected) | Usually 1-3 | | Protocol | **Open MCP standard** | Proprietary plugins | | Memory hierarchy | Vault → Shelf → Folder → Note | Flat | | Temporal decay | ✅ Ebbinghaus forgetting curve | ❌ | | Knowledge graph | ✅ Auto-linked memories | ❌ | | Fact-checking | ✅ Contradiction detection | ❌ | | Obsidian integration | Native import/export | ❌ | | Self-hosted | ✅ No cloud dependency | Often SaaS | | Open source | ✅ MIT license | Varies | ```bash pip install memorius ``` > **REST API server is included by default** — `fastapi`, `uvicorn`, `pydantic`, > and `sse-starlette` are now core dependencies. No extra `[rest]` install flag needed. ## Quick Start ```bash # 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 conversation memorius mine transcript.txt --vault conversations # Check status memorius status # Write a diary entry memorius diary --session "session-001" --title "Research findings" ``` ## Architecture ``` ┌────────────────────────────────────────────────────────────┐ │ Memorius │ ├────────────────────────────────────────────────────────────┤ │ CLI memorius init | store | search | mine | ... │ │ MCP JSON-RPC protocol server (stdin/stdout) │ │ REST FastAPI HTTP server │ │ 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 │ └────────────────────────────────────────────────────────────┘ ``` ## Configuration Config lives at `~/.memorius/config.yaml` (auto-created on `memorius init`): ```yaml storage: path: ~/.memorius/data embeddings: provider: chroma-default # chroma-default | sentence-transformers | openai model: all-MiniLM-L6-v2 vault: default: main server: mcp_port: 8910 rest_port: 8912 host: 127.0.0.1 retrieval: web_fallback: false # opt-in: augment thin local recall with web web_provider: duckduckgo # duckduckgo (keyless) | tavily (keyed) | mock (tests) tavily_api_key: null # or set TAVILY_API_KEY env var web_min_results: 1 # if ZERO local hits, fall back to web web_max_results: 5 # max web results to return ``` Environment variable overrides: | Variable | Overrides | |---|---| | `MEMORIUS_STORAGE_PATH` | `storage.path` | | `MEMORIUS_EMBEDDINGS_PROVIDER` | `embeddings.provider` | | `MEMORIUS_DEFAULT_VAULT` | `vault.default` | | `MEMORIUS_MCP_PORT` | `server.mcp_port` | | `MEMORIUS_REST_PORT` | `server.rest_port` | | `MEMORIUS_HOST` | `server.host` | | `MEMORIUS_OPENAI_API_KEY` | `embeddings.openai.api_key` | | `MEMORIUS_WEB_PROVIDER` | `retrieval.web_provider` | | `MEMORIUS_WEB_FALLBACK` | `retrieval.web_fallback` | | `MEMORIUS_TAVILY_API_KEY` | `retrieval.tavily_api_key` | ## Web Search When local recall is thin, Memorius can optionally augment retrieval with live web results. This is **local-first and opt-in** — web search never runs unless you ask for it: the `memorius web` command, the `--web` flag on `search` / `context` / `factcheck`, or `retrieval.web_fallback: true`. ```bash # Live web search (keyless DuckDuckGo by default) memorius web "python 3.13 changelog" # Use the keyed Tavily provider for higher signal-to-noise memorius web "python 3.13 changelog" --provider tavily # Augment a local search with web when local hits are thin memorius search "latest rust release" --web ``` ### Providers | Provider | Key | Notes | |---|---|---| | `duckduckgo` (default) | none | Keyless, stdlib-only scraper. Works out of the box. | | `tavily` | `TAVILY_API_KEY` or `MEMORIUS_TAVILY_API_KEY` | Agent-grade signal-to-noise. Missing key warns and returns `[]` — never crashes. | | `mock` | n/a | Test double for offline testing. | ### Configuration ```yaml retrieval: web_fallback: false # opt-in: augment thin local recall with web web_provider: duckduckgo # duckduckgo (keyless) | tavily (keyed) | mock (tests) tavily_api_key: null # or set TAVILY_API_KEY / MEMORIUS_TAVILY_API_KEY web_min_results: 1 # fall back to web only when local hits Store a memory --vault, -v Vault name (default: main) --shelf, -s Shelf name (default: default) --folder, -f Folder name (default: default) --note, -n Note name (default: default) memorius search Semantic search --vault, -v Filter by vault --shelf, -s Filter by shelf --n Max results (default: 10) memorius mine Extract memories from transcript --vault, -v Target vault (default: main) memorius diary Write a diary entry --title, -t Entry title --summary, -s Entry summary --vault, -v Vault name (default: main) memorius diaries List recent diary entries memorius ls Explore vault hierarchy memorius consolidate Merge duplicate memories --vault Filter by vault --threshold Similarity threshold 0-1 (default: 0.80) --dry-run Preview without changes memorius extract Extract memories from conversation (LLM) --vault Target vault (default: main) --shelf Target shelf (default: extracted) --backend LLM backend: auto|openai|ollama|regex memorius factcheck Fact-check against stored memories --vault Filter by vault memorius context Get formatted memory context for injection --vault Filter by vault --max Max items (default: 5) memorius profile Build session memory profile --vault Vault name (default: main) memorius stats Show vault + memory + graph statistics memorius serve Start MCP server (stdio) memorius serve-rest Start REST API server memorius web Live web search (keyless DuckDuckGo by default) --provider duckduckgo (keyless) | tavily (keyed via TAVILY_API_KEY) --max Max results (default: 5) memorius --version Show version memorius config Show current configuration memorius delete Delete a memory by ID (validation + confirmation) --vault, -v Vault scope (must match the memory's vault) --shelf, -s Shelf scope (must match the memory's shelf) --yes, -y Skip the confirmation prompt --dry-run Preview what would be deleted (no changes) ``` ### Obsidian integration ```bash memorius obsidian list Explore vault structure --vault, -v Path to Obsidian vault directory (default: $OBSIDIAN_VAULT_PATH or ~/Documents/Obsidian Vault) memorius obsidian import Import Obsidian notes as memorius memories --vault, -v Path to Obsidian vault --target-vault Target memorius vault (default: main) --target-shelf Target memorius shelf (default: obsidian) --tag Only import notes with this tag --dry-run Preview without importing memorius obsidian export Export memorius memories as Obsidian notes --vault, -v Path to Obsidian vault --source-vault Source memorius vault (default: main) --source-shelf Filter by shelf (default: all) --dry-run Preview without exporting ``` Import preserves the file hierarchy: `vault/Subfolder/note.md` maps to `vault/Subfolder/vault > shelf > folder > note`. YAML frontmatter is parsed and stored as memory attributes. ## MCP Protocol MCP is the primary interface for AI agents to interact with Memorius. Connect any MCP-compatible client by pointing it at the MCP server: ```json { "mcpServers": { "memorius": { "command": "memorius", "args": ["serve"] } } } ``` Available MCP tools: | Tool | Description | |---|---| | `memorius_status` | Memory vault status | | `memorius_store` | Store content in vault/shelf/folder/note hierarchy | | `memorius_search` | Semantic search across vault | | `memorius_mine` | Extract memories from conversation | | `memorius_diary_write` | Write session diary entry | | `memorius_diary_list` | List diary entries | | `memorius_vault_ls` | Browse vault hierarchy | | `memorius_consolidate` | Merge duplicate memories, extract insights | | `memorius_extract` | Extract structured memories from conversation (LLM) | | `memorius_factcheck` | Fact-check a statement against stored memories | | `memorius_context` | Get formatted memory context for injection | | `memorius_session_profile` | Build session memory profile for inheritance | | `memorius_graph_stats` | Knowledge graph statistics | | `memorius_memory_stats` | Memory tracking statistics | ## Agent Skill Installation Memorius ships with a ready-to-use agent skill (`skills/memorius/SKILL.md`) for agents that support the Hermes Agent skill format. The skill provides auto-capture rules, smart context injection, session diary templates, and workflow patterns — so agents can use memorius proactively without being told. ### Skill Structure ``` skills/ memorius/ SKILL.md # Full skill definition (auto-capture, context injection, diary rules) README.md # Quick command reference .memorius_version # Version tracker ``` ### Installing for Hermes Agent The skill is designed for [Hermes Agent](https://hermes-agent.nousresearch.com) — copy it into your Hermes skills directory: ```bash # Copy the skill cp -r skills/memorius ~/.hermes/skills/ # Verify it's loaded hermes skills list | grep memorius ``` Once installed, Hermes will automatically detect it and follow the skill's workflows. ### Installing for Other Agents Agents that don't use the Hermes skill format can still use memorius via MCP or CLI: | Agent | Install Command | |-------|----------------| | Claude Code | `claude mcp add memorius -- memorius serve` | | Codex CLI | `codex mcp add memorius -- memorius serve` | | Gemini CLI | `gemini mcp add memorius $(which memorius) serve` | | Cursor | Add to `.cursor/mcp.json`: `{"mcpServers": {"memorius": {"command": "memorius", "args": ["serve"]}}}` | | Aider | `aider --mcp-servers memorius=memorius serve` | | Continue | Add memorius to `.continue/config.json` MCP servers | | OpenClaw | `openclaw mcp set memorius '{"command":"memorius","args":["serve"]}'` | See `manifest.yaml` for the full list of supported agents and their install commands. Copying the SKILL.md file directly may also work for agents with their own skills directory (e.g. `~/.claude/skills/`, `~/.codex/skills/`) — check your agent's documentation. ## REST API The REST server is always available (no extra install flags needed): ```bash memorius serve-rest ``` Starts a FastAPI server on `http://127.0.0.1:8912` by default. | Method | Path | Description | |---|---|---| | GET | `/health` | Health check | | GET | `/status` | System status | | GET | `/stats` | Full vault + memory + graph stats | | POST | `/store` | Store a memory | | POST | `/search` | Semantic search | | POST | `/mine` | Extract memories from transcript | | POST | `/diary` | Write diary entry | | GET | `/vault` | Browse vault hierarchy | | GET | `/diaries` | List recent diary entries | | POST | `/consolidate` | Merge duplicate memories | | POST | `/extract` | Extract memories from conversation (LLM) | | POST | `/factcheck` | Fact-check statement against vault | | POST | `/context` | Get formatted memory context for injection | | GET | `/obsidian` | List notes in Obsidian vault | | POST | `/obsidian/import` | Import Obsidian notes as memories | | POST | `/obsidian/export` | Export memories as Obsidian notes | ## Agent Hooks Memorius includes **universal agent lifecycle hooks** — auto-detecting, agent-agnostic, and framework-free. Hook scripts are generated per agent: ```bash memorius-plugin-gen init # Edit universal-manifest.yaml memorius-plugin-gen generate ``` ### Supported agents | Agent | Hook protocol | Events | |---|---|---| | **Claude Code** (Anthropic) | `stop_hook_active` / `precompact` | stop, precompact, session_start | | **Codex CLI** (OpenAI) | `session_id` + `context_dir` | session_start, session_stop | | **Gemini CLI** (Google) | `conversation_id` + `extensions` | stop, session_start | | **OpenClaw** | `openclaw` marker in payload | stop, session_stop, precompact, session_start | | **OpenCode** (anomalyco/sst) | `provider` dict + `openCodeVersion` | stop, session_stop, session_start, precompact | | **Pi** (kachow-compatible) | `event` in Pi event set | session_start, session_shutdown, pre_compact, tool_call, turn_end | | **OpenClaude** | `OpenClaude` marker in payload | stop, precompact, session_start | ### Auto-detection (no config needed) Hooks are auto-detected from stdin — no `--agent` flag required. Just pipe agent hook JSON to the memorius hook engine and it figures out which agent sent the event: ```bash # Hook engine auto-detects the agent cat hook-payload.json | memorius-hook mine cat hook-payload.json | memorius-hook diary ``` You can also force a specific agent with `--agent`: ```bash memorius-hook mine --agent claude-code memorius-hook diary --agent opencode ``` Detection priority (most-specific first): `OpenClaude → Claude Code → Codex → Gemini CLI → OpenClaw → OpenCode → Pi → Generic` ## Plugin Generator (optional) ```bash memorius-plugin-gen list # Show supported agents memorius-plugin-gen init # Create universal-manifest.yaml memorius-plugin-gen generate # Generate plugins for all agents ``` ## Conversation Normalizers (optional) ```bash memorius-normalize input.json # Auto-detect and normalize memorius-normalize input.json --format discord ``` Supported formats: Discord, Telegram, WhatsApp, generic JSON, plain text. ## Development ```bash git … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Dream-Pixels-Forge](https://github.com/Dream-Pixels-Forge) - **Source:** [Dream-Pixels-Forge/memorius](https://github.com/Dream-Pixels-Forge/memorius) - **License:** MIT - **Homepage:** https://dream-pixels-forge.github.io/memorius/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-dream-pixels-forge-memorius - Seller: https://agentstack.voostack.com/s/dream-pixels-forge - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.