mnemos

Agent (Claude Code / Cursor / Kiro / Gemini CLI / ...)
 ↓ MCP stdio
mnemos serve
 ↓
Auto-compiled knowledge base (~/.mnemos/mnemos.db)

Agent action → mnemos auto-pipeline:
 ├── Quality gate (reject/rewrite low-value content)
 ├── 3-tier dedup (hash → fuzzy → semantic)
 ├── Auto-summarize (extractive, fast; LLM if available)
 ├── File linking (extract identifiers, link to code)
 ├── Type classification (episodic / long_term / semantic / working)
 ├── Quality scoring (for retrieval ranking)
 └── Decay scheduling (so knowledge base stays relevant)

Retrieval:
 ├── Hybrid search (FTS5 + optional semantic + RRF)
 ├── File-overlap boost (memories about active files rank higher)
 ├── MMR diversity (kill redundant results)
 ├── Adaptive packing (full content or summary based on budget)
 └── Token-budget cap (always fits in context)

# Homebrew (macOS / Linux)
brew install s60yucca/tap/mnemos && mnemos setup claude

# curl (verify mnemos.dev is live before using)
curl -fsSL https://mnemos.dev/install.sh | bash && mnemos setup claude

# npm (coming in v1.2)
# npx mnemos setup claude

# Build from source (requires Go 1.23+)
git clone https://github.com/s60yucca/mnemos
cd mnemos && make build

mnemos autopilot status # check daemon state
mnemos autopilot run # trigger immediate run
mnemos autopilot run --dry-run # preview findings without writing
mnemos autopilot report # view latest findings

# Agents call these automatically via MCP. You can also use directly:
mnemos store "JWT uses RS256, 1h expiry, config in auth/config.go"
mnemos search "token expiry"
mnemos stats
mnemos maintain

# ~/.mnemos/config.yaml
embeddings:
 provider: noop # noop (default) | ollama | openai
 # Pure FTS works fine. Enable semantic for meaning-based search.

quality_gate:
 min_words: 5
 max_words: 200
 min_density: 0.3
 require_specific: true # long_term memories need project identifiers
 duplicate_threshold: 0.8

summarization:
 extractive: true # always on, fast, offline

file_linking:
 enabled: true # auto-disables outside git

hook:
 enabled: true
 search_cooldown: 5m
 session_start_max_tokens: 2000
 mmr_lambda: 0.7 # 0=max diversity, 1=max relevance
 file_boost: 0.3

autopilot:
 enabled: true
 interval: 15m
 contradiction_enabled: false

mnemos setup claude # writes CLAUDE.md, .claude/hooks.json, .mcp.json
mnemos setup cursor # writes .cursorrules, .mcp.json
mnemos setup kiro # writes .kiro/steering/mnemos.md, .kiro/mcp.json
mnemos setup gemini-cli # writes GEMINI.md, .gemini/settings.json, .mcp.json

mnemos init # first-time setup
mnemos store "..." # store (auto-pipeline)
mnemos search "auth" # hybrid search
mnemos list --project myapp # list memories
mnemos get <id> # fetch by id
mnemos update <id> --content "..." # update
mnemos delete <id> # soft delete
mnemos relate <src> <tgt> --type supersedes # typed relation
mnemos stats # storage + quality stats
mnemos maintain # decay + stale + GC
mnemos serve # MCP server (stdio)
mnemos version

# Autopilot setup
mnemos setup claude | cursor | kiro | gemini-cli [--global] [--force]

# Passive autopilot daemon
mnemos autopilot status
mnemos autopilot run [--dry-run] [--project <id>]
mnemos autopilot report [--project <id>]

# Backfill
mnemos backfill summaries --project <id> [--dry-run] [--limit N]

# Hook subcommands (called by clients, not manually)
mnemos hook session-start
mnemos hook prompt-submit
mnemos hook session-end