mastermind

Persistent memory for AI coding agents — survives sessions, projects, and years.

mastermind gives your AI coding agent long-term memory. It captures lessons, decisions, patterns, and war stories from your sessions and surfaces them automatically when relevant — so you stop re-debugging the same bugs and re-making the same decisions.

Built as an MCP server with CLI hooks for Claude Code. Single Go binary, zero runtime dependencies, plain markdown files synced with git.

How it works

Session starts
  → mastermind injects relevant knowledge + open loops (SessionStart hook)

You work normally
  → agent reads a file → mastermind nudges: "DOMPurify strips details/summary by default" — consider mm_search
  → agent discovers something worth keeping → calls mm_write

Context gets compressed
  → mastermind extracts lessons from the conversation (PreCompact hook)
  → extracted entries land in pending/ for review

Next session
  → knowledge compounds automatically

No commands to remember. No dashboards. The default state is invisible.

Install

For Codex:

git clone https://github.com/jeanfbrito/mastermind.git
cd mastermind
./install/codex.sh

See docs/CODEX.md for portable options, including custom agent homes and prebuilt binary paths.

For a standalone binary:

go install github.com/jeanfbrito/mastermind/cmd/mastermind@latest

Or build from source:

git clone https://github.com/jeanfbrito/mastermind.git
cd mastermind
make build && make install

Requires Go 1.25+.

Claude Code setup

1. Register the MCP server

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "mastermind": {
      "type": "stdio",
      "command": "mastermind"
    }
  }
}

2. Configure the hooks

Add to ~/.claude/settings.json under "hooks":

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "mastermind session-start" }]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "mastermind extract --from-hook" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [{ "type": "command", "command": "mastermind suggest --from-hook" }]
      }
    ]
  }
}

3. Initialize the knowledge store

mkdir ~/.knowledge && cd ~/.knowledge && git init

Project-level stores (<repo>/.knowledge/) are created automatically on first use. Opt out with MASTERMIND_NO_AUTO_INIT=1.

Knowledge scopes

mastermind organizes knowledge into three scopes, all searched automatically:

Scope	Location	Synced via	Use case
user-personal	`~/.knowledge/`	personal git remote	General engineering lessons that apply across all projects
project-shared	`<repo>/.knowledge/`	committed to repo	Project-specific knowledge shared with the team
project-personal	`~/.claude/projects/<slug>/memory/`	personal git	Private notes about a specific project

mm_search fans out to all three scopes and returns source-tagged, ranked results.

MCP tools

Tool	Description
`mm_search`	Search knowledge across all scopes. Called proactively by the agent at task start.
`mm_write`	Write an entry to the live store. The agent calls this when it discovers something worth preserving.
`mm_promote`	Promote a pending entry (from auto-extraction) to the live store after review.
`mm_close_loop`	Resolve an open loop. Archives the entry to `resolved-loops/` so it stops surfacing.

Hooks

Hook	Trigger	Action
SessionStart	Session opens	Injects open loops and project-relevant knowledge into the agent's context
PreCompact	Before context compression	Extracts lessons from the conversation transcript into `pending/`
PostToolUse	After Read, Edit, or Write	Nudges the agent when relevant knowledge exists for the file being touched

Skills (optional)

mastermind ships three agent skills for manual workflows:

Skill	Trigger	Description
mm-extract	`/mm-extract`	Review the conversation and extract all lessons, decisions, patterns into mastermind
mm-review	`/mm-review`	Verify pending entries against their sources (commits/files), auto-promote clean ones, auto-reject hallucinations, escalate only ambiguous cases to you
mm-discover	`/mm-discover [git\|codebase\|all]`	Mine the codebase and git history for knowledge using Haiku subagents (near-zero cost)

Install by symlinking into your agent skills directory:

ln -s /path/to/mastermind/skills/mm-extract ~/.claude/skills/mm-extract
ln -s /path/to/mastermind/skills/mm-review ~/.claude/skills/mm-review
ln -s /path/to/mastermind/skills/mm-discover ~/.claude/skills/mm-discover

For Codex, ./install/codex.sh installs these into ~/.codex/skills.

These are optional — the hooks handle capture and retrieval automatically. Skills are for when you want manual control: extracting knowledge before session end, reviewing what auto-extraction captured, or seeding knowledge from an existing codebase.

Entry format

Every entry is a markdown file with YAML frontmatter:

---
date: 2026-04-09
project: my-project
tags: [electron, webview, security]
topic: DOMPurify strips details/summary elements by default — must allowlist
kind: lesson
scope: project-shared
category: electron/security
confidence: high
---

## What happened
Used DOMPurify to sanitize markdown output. The <details> and <summary>
elements were silently stripped — they're not in DOMPurify's default allowlist.

## Fix
Add ALLOWED_TAGS: ['details', 'summary'] to the DOMPurify config.

## Rule
Always check DOMPurify's default allowlist when HTML elements disappear.

Entry kinds: lesson · insight · war-story · decision · pattern · open-loop

See docs/FORMAT.md for the full schema.

Optional LLM extraction

By default, knowledge extraction uses keyword/regex matching with zero external dependencies. For higher-quality extraction, enable LLM mode:

# Use Anthropic API (Haiku)
export MASTERMIND_EXTRACT_MODE=llm

# Or use a local model via Ollama
export MASTERMIND_EXTRACT_MODE=llm
export MASTERMIND_LLM_PROVIDER=ollama

Standalone discovery

Mine git history and source code for knowledge without a Claude Code session. Runs directly against Anthropic Haiku or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, Together.ai, Groq, etc.).

# With Anthropic Haiku (default)
mastermind discover --mode git --depth 50

# With a local model via Ollama
MASTERMIND_LLM_PROVIDER=openai mastermind discover

# With a hosted OpenAI-compatible provider
MASTERMIND_LLM_PROVIDER=openai \
MASTERMIND_LLM_BASE_URL=https://api.together.xyz/v1 \
MASTERMIND_LLM_API_KEY=your-key \
MASTERMIND_LLM_MODEL=meta-llama/Llama-3-8b-chat-hf \
mastermind discover --mode all --depth 200

Modes: git (mine commit history), codebase (scan packages), all (both). Entries land in pending/ — review with /mm-review.

Fully incremental: ## Source sections in entries track which commits have been analyzed. Running again only processes new commits.

Configuration

Environment variable	Default	Description
`MASTERMIND_NO_AUTO_INIT`	(unset)	Set to `1` to disable automatic `.knowledge/` creation in git repos
`MASTERMIND_EXTRACT_MODE`	`keyword`	`keyword` for regex-based extraction, `llm` for model-powered extraction
`MASTERMIND_LLM_PROVIDER`	`anthropic`	`anthropic` or `openai` (OpenAI-compatible endpoint)
`MASTERMIND_LLM_MODEL`	(auto)	Model identifier (defaults to Haiku for Anthropic, llama3.2 for OpenAI)
`MASTERMIND_LLM_BASE_URL`	`http://localhost:11434/v1`	Base URL for OpenAI-compatible providers
`MASTERMIND_LLM_API_KEY`	(unset)	API key for OpenAI-compatible providers (optional for local models)
`MASTERMIND_OLLAMA_URL`	`http://localhost:11434`	Ollama API endpoint (for extract hook, legacy)
`ANTHROPIC_API_KEY`	(unset)	Anthropic API key (for Haiku extraction and discovery)

Design principles

Zero friction. Capture and retrieval happen through hooks, not commands. The tool works on autopilot — nothing to remember, nothing to maintain.
Plain markdown + git. No database. Files on disk are the store, git is the sync layer. A markdown file written today will still parse in 2034.
Zero runtime dependencies. Single static Go binary. No Python, no Node, no Docker, no Postgres.
Scoped sharing. Personal knowledge stays personal. Project knowledge lives in the repo, versioned and shareable. The boundary is explicit.

Non-goals

No server, hub, or cloud account
No vector store or embeddings — keyword search scales to career-length corpora
No code or file path storage — only insights, lessons, decisions, and patterns

Documentation

Doc	Contents
CONTINUITY.md	Core behaviors: session-start injection, extraction, open-loop lifecycle
CODEX.md	Codex MCP and skill install
ARCHITECTURE.md	Package layout, MCP tool surface, hook integration
FORMAT.md	Entry schema — the long-term contract
DECISIONS.md	Architectural decision log
ROADMAP.md	Planned work

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.knowledge		.knowledge
cmd/mastermind		cmd/mastermind
docs		docs
install		install
internal		internal
plugins/hermes-memory-provider		plugins/hermes-memory-provider
skills		skills
testdata/audit		testdata/audit
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Navigation Menu

Repository navigation

About

Repository files navigation

mastermind

How it works

Install

Claude Code setup

1. Register the MCP server

2. Configure the hooks

3. Initialize the knowledge store

Knowledge scopes

MCP tools

Hooks

Skills (optional)

Entry format

Optional LLM extraction

Standalone discovery

Configuration

Design principles

Non-goals

Documentation

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

mastermind

How it works

Install

Claude Code setup

1. Register the MCP server

2. Configure the hooks

3. Initialize the knowledge store

Knowledge scopes

MCP tools

Hooks

Skills (optional)

Entry format

Optional LLM extraction

Standalone discovery

Configuration

Design principles

Non-goals

Documentation

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages