How it works

Overview

The vault engine is the single source of truth. CLI, MCP, REST, and hooks are thin frontends over the same storage and search stack.

┌────────────────────────────────────────────────────────────┐
│                       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)   │
│  └── KnowledgeGraph Typed edges + spreading activation     │
├────────────────────────────────────────────────────────────┤
│  Consolidation Engine                                      │
│  ├── Interference Forgetting  decay by relatedness        │
│  ├── Engram Maturation        trace → memory → schema    │
│  └── Neuromodulator Gating    dopamine/sedation modulation │
├────────────────────────────────────────────────────────────┤
│  Vault  >  Shelf  >  Folder  >  Note  hierarchy           │
│  Diaries          Session diary entries                    │
│  Mine             Extract memories from transcripts        │
└────────────────────────────────────────────────────────────┘

• Vault engine — 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.
• Knowledge graph with typed edges and spreading activation for multi-hop recall.
• Consolidation models biological memory: interference forgetting, engram maturation, and neuromodulator gating.
• Hooks auto-detect which agent sent the event from the JSON payload — no --agent flag required.

5-stage search pipeline

Every query passes through five stages; the final score blends semantic similarity, temporal decay, and access frequency.

Search ranking = semantic similarity (60%) + temporal decay (25%) + access frequency (15%). Hybrid retrieval fuses vector + BM25/FTS5 keyword search, so keyword blind-spots don't drop results. See Memory Engine for the decay model.

Embedding providers

Swap providers with one config change (embeddings.provider). Custom runtime providers can be registered via EmbeddingFactory.register().

Vector store backends

A VectorStore ABC makes the backend swappable. Both implement the same interface: add, delete, search, get_collections, count, get_by_ids.

Set storage.type: sqlite-vec in config or MEMORIUS_STORAGE_TYPE=sqlite-vec to use the lightweight backend. HNSW tuning knobs live under vector_optimization.

Knowledge graph

• Auto-linking on every store() by content proximity (Jaccard word overlap or vector cosine).
• BFS expansion from search results (--expand-graph).
• Contradiction edges persisted by factcheck (bidirectional relation='contradicts').
• Typed edges — related, references, contradicts, co_occurs, plus temporal_before, causal_leads_to, episodic_part_of, semantic_instance_of.
• Spreading activation for multi-hop recall; graph view / graph export-html for visualization.

Configuration

Config lives at ~/.memorius/config.yaml (auto-created on memorius init). A ./memorius.yaml in the current directory takes precedence.

storage:
  type: chroma            # chroma (default) | sqlite-vec
  path: ~/.memorius/data

embeddings:
  provider: chroma-default  # chroma-default | sentence-transformers | openai
  model: all-MiniLM-L6-v2

server:
  mcp_port: 8911
  rest_port: 8912
  host: "127.0.0.1"

vault:
  default: "main"
  max_note_size: 1000

hooks:
  enabled: true
  config: ~/.memorius/hooks.yaml

retrieval:
  web_fallback: false       # opt-in: augment thin local recall with web
  web_provider: duckduckgo  # duckduckgo (keyless) | tavily (keyed) | mock
  tavily_api_key: null      # or set TAVILY_API_KEY
  web_min_results: 1
  web_max_results: 5

consolidation:
  enabled: false
  dedup_threshold: 0.92
  contradiction_check: true

vector_optimization:
  enable_hnsw_optimization: false
  hnsw_ef_construction: 100
  hnsw_ef_search: 100
  hnsw_max_m: 16

Environment variable overrides

Validation & thread safety

Input validation — names match ^[a-zA-Z0-9_\-]+$ (max 1000 chars), memory IDs must be valid UUIDs (blocks path traversal), content capped at 100KB, search limit capped at 100 results, diary content at 50KB, and a body-size middleware on the REST server.

Thread safety — thread-local SQLite connections, a threading.Lock() on all metadata writes and on the sqlite-vec store, and an atexit handler that closes connections.