mnemonic

mnemonic

Attention-based MCP memory controller for LLM coding agents.

Installation

go install github.com/jimschubert/mnemonic/cmd/mnemonic@latest

Or, check the releases page for binaries.

Usage

mnemonic --help

Commands

• stdio (default) — Serve MCP over stdio, automatically starting the server in the background if needed.
• server — Start the MCP HTTP server, which also manages memory storage.
• embed — Fetch embeddings and build the HNSW index for the active project.
• stop — Send a shutdown request to the running background server.

Configuration

Config file precedence

Configuration is resolved in order of precedence (highest wins):

1. CLI flags (e.g., --server-addr localhost:9999)
2. Environment variables (e.g., MNEMONIC_SERVER_ADDR=localhost:9999)
3. .mnemonic/config.yaml — project-local config (relative to where mnemonic is invoked)
4. ~/.mnemonic/config.yaml — global/user config
5. Struct defaults defined in code

Example config file

Global config (~/.mnemonic/config.yaml):

log_level: info
server_addr: localhost:20001
socket_path: ~/.mnemonic/mnemonic.sock
client_timeout_sec: 5

# optional scoped logging levels
logging:
  store: debug
  server: warn

# optional embeddings configuration
embeddings:
  endpoint: http://127.0.0.1:1234/v1/embeddings
  model: nomic-ai/nomic-embed-text-v1.5

Project config (.mnemonic/config.yaml):

log_level: debug
server_addr: localhost:9999

For available config options, see Config struct.

Team directories

Pass one or more --team directories to load an additional shared scope per directory. Each team directory is registered as scope team:<basename>, so /shared/acme becomes scope team:acme and can be referenced in your agent to access team-specific memory.

For example:

mnemonic server --team /shared/acme --team /shared/platform --server-addr localhost:9999

MCP server

Example MCP configuration (Claude Desktop, Cursor, Zed, JetBrains IDEs):

{
  "mcpServers": {
    "mnemonic": {
      "command": "mnemonic",
      "args": ["stdio"]
    }
  }
}

If your client only supports HTTP transports, use mnemonic server and connect to http://localhost:20001/mcp.

Example memory instructions:

## Memory
Before starting any task, call `mnemonic_query` with a description of
the work to retrieve relevant rules and lessons. Always query the
`avoidance` and `security` categories.

All available categories:
- avoidance   — mistakes, wrong approaches, things that don't work
- security    — security concerns or constraints
- architecture — design decisions and why they were made
- syntax      — code patterns that worked well
- domain      — project-specific knowledge

DO NOT create new categories without explicit instructions. If a new category is needed, add it to the list above and inform the user.

Set default scope to "project". Set default source to "agent:YYYY-MM-DD".

If the user prompt includes "remember this" or "add this to memory", always call `mnemonic_add` with the content.
Call `mnemonic_reinforce` with delta +0.1 for confirmed patterns, -0.2 for rejected ones.

License

Apache 2.0 – see LICENSE