memorius 0.1.1

Self-contained memory vault for any AI agent — vector search, session diaries, and agent-agnostic hooks.

Memorius

Universal memory vault for any AI agent.

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.

pip install memorius

Quick Start

# 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 (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                 │
└────────────────────────────────────────────────────────────┘

Configuration

Config lives at ~/.memorius/config.yaml (auto-created on memorius init):

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

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

Embedding Providers

Provider	Requirement	Quality
chroma-default	ChromaDB (bundled ONNX)	Good (384d)
sentence-transformers	pip install memorius[local-embeddings]	Better (768d+)
openai	OPENAI_API_KEY env var	Best (1536d)

CLI Reference

Core commands

memorius init                Initialize a new vault
memorius status              Show vault status
memorius store <text>        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 <query>      Semantic search
  --vault, -v                  Filter by vault
  --shelf, -s                  Filter by shelf
  --limit, -l                  Max results (default: 10)
memorius mine <file|text>    Extract memories from transcript
  --vault, -v                  Target vault (default: main)
memorius diary <session>     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 serve                Start MCP server (stdio)
memorius serve-rest           Start REST API server
memorius --version            Show version
memorius config               Show current configuration

Obsidian integration

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:

{
  "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

REST API

memorius serve-rest

Method	Path	Description
GET	/health	Health check
POST	/store	Store a memory
POST	/search	Semantic search
POST	/mine	Extract memories
GET	/status	System status
POST	/diary	Write diary entry
GET	/palace	Browse hierarchy

Agent Hooks

Memorius includes universal agent lifecycle hooks — auto-detecting, agent-agnostic, and framework-free. Hook scripts are generated per agent:

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:

# 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:

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)

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)

memorius-normalize input.json     # Auto-detect and normalize
memorius-normalize input.json --format discord

Supported formats: Discord, Telegram, WhatsApp, generic JSON, plain text.

Development

git clone https://github.com/Dream-Pixels-Forge/memorius.git
cd memorius
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Run end-to-end
memorius init
memorius store "test memory"
memorius search "test"

License

MIT