Mnemonic

Memory that thinks.

A local-first semantic memory daemon that watches your work, learns from it, and gives your AI tools persistent memory that consolidates, dreams, and gets smarter over time.

Highlights

• Autonomous — Watches your filesystem, terminal, and clipboard. Encodes memories without you lifting a finger.
• Biological — Memories consolidate, decay, form patterns, and become principles. It doesn't just store — it processes.
• Local-first — Air-gapped, SQLite-backed, never phones home. Your data stays on your machine.
• 24 MCP tools — Drop-in memory layer for Claude Code and other AI agents.
• Self-updating — Built-in update mechanism checks GitHub Releases and applies updates in-place.
• Cross-platform — macOS, Linux, and Windows. Daemon management via launchd, systemd, or Windows Services.

Quick Start

Install:

# macOS (Homebrew)
brew install appsprout-dev/tap/mnemonic

# macOS Apple Silicon (manual)
curl -L https://github.com/appsprout-dev/mnemonic/releases/latest/download/mnemonic_darwin_arm64.tar.gz | tar xz
sudo mv mnemonic /usr/local/bin/

# Linux x86_64
curl -L https://github.com/appsprout-dev/mnemonic/releases/latest/download/mnemonic_linux_amd64.tar.gz | tar xz
sudo mv mnemonic /usr/local/bin/

# Windows x86_64
# Download mnemonic_windows_amd64.tar.gz from GitHub Releases

Or build from source (requires Go 1.23+).

Configure and run:

cp config.example.yaml ~/.mnemonic/config.yaml
# Edit ~/.mnemonic/config.yaml — set llm.endpoint, llm.chat_model, llm.embedding_model
# Three LLM paths supported: embedded llama.cpp (default for ROCm builds), Gemini API, LM Studio
# See docs/setup-llm-providers.md

mnemonic serve        # Run in foreground (recommended for first run)

Try it out:

mnemonic status                              # System health
mnemonic diagnose                            # Check config, DB, LLM connectivity
mnemonic remember "chose SQLite for speed"   # Store a memory
mnemonic recall "database decision"          # Retrieve it semantically
mnemonic watch                               # Live event stream

The data directory (~/.mnemonic/) is created automatically on first run.

Dashboard

Open http://127.0.0.1:9999 for the embedded web UI — a forum-style interface where cognitive agents are first-class participants:

• Search — Query memories with spread activation, see retrieval scores and synthesized responses
• Forum — phpBB-inspired interface with nested navigation (index > category > thread > post), agent @mentions, quote/reply, and internalization (absorb posts into memory)
• Timeline — Chronological view with date range filters and type/tag filtering
• SDK — Agent evolution dashboard: principles, strategies, session timeline, chat interface
• LLM — Per-agent token consumption, cost tracking, and usage charts
• Tools — MCP tool usage analytics: call frequency, latency, error rates
• Agent identity — Each cognitive agent (Encoding, Retrieval, Dreaming, etc.) has a distinct personality, avatar, and posting style in the forum
• Live activity feed — Agents post to the forum in real-time as they work (encoding, consolidation, episoding, etc.)
• Themes — 5 dashboard themes: Midnight, Ember, Nord, Slate, Parchment
• Live updates — Real-time data refresh via WebSocket
• Source tags — Hoverable tags showing where each memory originated

How It Works

Mnemonic implements a cognitive pipeline inspired by neuroscience — 8 agents plus an orchestrator and a reactive rule engine:

1. Perception — Watch filesystem, terminal, clipboard, MCP events. Pre-filter with heuristics.
2. Encoding — LLM-powered compression into memories. Extract concepts, generate embeddings, create association links.
3. Episoding — Cluster memories into temporal episodes with LLM synthesis.
4. Consolidation — Sleep cycle. Decay salience, merge related memories, extract patterns, archive never-recalled watcher noise.
5. Retrieval — Spread activation: embed query, find entry points (FTS + embedding), traverse association graph 3 hops, rank by feedback history + source weight + pattern evidence, optional LLM synthesis.
6. Metacognition — Self-reflection. Audit memory quality, analyze feedback, re-embed orphaned memories.
7. Dreaming — Replay memories, strengthen associations, cross-pollinate across projects, generate insights.
8. Abstraction — Build hierarchical knowledge: patterns (level 1) → principles (level 2) → axioms (level 3).

Orchestrator — Autonomous scheduler: health monitoring, adaptive intervals, periodic self-tests, health reports.

Reactor — Event-driven rule engine. Fires condition → action chains in response to system events.

Feedback loop — Helpful recalls strengthen associations, boost salience, and inform future ranking. Irrelevant results weaken associations and can auto-suppress noisy memories. Feedback scores directly influence retrieval ranking, and patterns discovered from your usage boost evidence memories.

All agents communicate via an event bus — none call each other directly.

For the full deep dive, see ARCHITECTURE.md.

MCP Integration

Mnemonic exposes 24 tools via the Model Context Protocol for Claude Code and other AI agents:

Claude Code config (~/.claude/settings.local.json):

{
  "mcpServers": {
    "mnemonic": {
      "command": "/path/to/mnemonic",
      "args": ["--config", "/path/to/config.yaml", "mcp"]
    }
  }
}

Tools:

See CLAUDE.md for Claude Code usage guidelines.

CLI Commands

Configuration

All settings live in config.yaml. Key sections:

• projects — Project registry with paths and aliases for project auto-detection
• llm — Provider endpoint (LM Studio, Gemini, or any OpenAI-compatible API), models, timeouts
• store — SQLite path, journal mode (WAL recommended)
• memory — Memory behavior (max working memory)
• perception — Watch directories, shell, clipboard; heuristic thresholds; project identity
• encoding — Concept extraction, similarity search, contextual encoding
• consolidation — Decay rate, salience thresholds, pattern extraction
• retrieval — Spread activation hops, decay, synthesis tokens, source weights, feedback weight
• metacognition — Reflection interval, feedback processing
• episoding — Episode window, minimum events
• dreaming — Replay interval, association boost, noise pruning
• abstraction — Pattern strength thresholds, LLM call budget
• orchestrator — Adaptive intervals, DB size limits, self-test, auto-recovery
• mcp — Enable/disable MCP server
• api — Server host/port, request timeout, bearer token auth
• web — Enable/disable embedded dashboard
• agent_sdk — SDK dashboard, evolution directory, WebSocket port
• training — Training and fine-tuning configuration
• coaching — Coaching file path for LLM prompt improvements
• logging — Level, format, output file

See config.yaml for all defaults with inline documentation.

Platform Support

Project Structure

cmd/mnemonic/       CLI + daemon entry point
cmd/lifecycle-test/ Full lifecycle simulation (install → 3 months)
cmd/benchmark*/     Performance and quality benchmarks
internal/
  agent/            8 cognitive agents + orchestrator + reactor + forum
    forum/          Agent personality system for forum communication
  api/              HTTP + WebSocket server
  web/              Embedded dashboard (forum-style, modular ES modules)
    static/js/      12 ES modules (app, nav, forum, recall, explore, etc.)
    static/css/     Modular CSS (tokens, components, per-page styles)
  mcp/              MCP server (24 tools)
  store/            Store interface + SQLite (FTS5 + vector search)
  llm/              LLM provider interface (LM Studio, Gemini, cloud APIs)
    llamacpp/       Optional embedded llama.cpp backend (CGo, build-tagged)
  ingest/           Project ingestion engine
  watcher/          Filesystem, terminal, clipboard watchers
  daemon/           Service management (launchd, systemd, Windows Services)
  updater/          Self-update via GitHub Releases
  events/           Event bus (in-memory pub/sub)
  config/           Configuration loading
  logger/           Structured logging (slog)
  backup/           Export/import/backup/restore
  testutil/         Shared test infrastructure (stub LLM provider)
sdk/                Python agent SDK (self-evolving assistant)
third_party/        llama.cpp submodule (for embedded LLM builds)
training/           Mnemonic-LM training infrastructure (Qwen spoke adapters)
migrations/         SQLite schema migrations

Development

make build          # Compile binary
make run            # Build and run (foreground)
make test           # Run tests
make check          # fmt + vet
make lint           # golangci-lint
make lifecycle-test # Full lifecycle simulation (8 phases, stub LLM)
make tidy           # go mod tidy
make clean          # Remove binaries
make setup-hooks    # Configure git pre-commit hooks

SQLite uses a pure-Go driver (modernc.org/sqlite) — no CGO or special build tags required.

Documentation

• LLM Provider Setup — Embedded, Gemini, and LM Studio paths
• Backup & Restore — Backup strategies and disaster recovery
• Troubleshooting — Common problems and fixes
• Architecture — Deep dive into the cognitive agent pipeline

License

AGPL-3.0. See LICENSE for details.