mcp-brain-tools

An MCP server that gives AI agents persistent memory with built-in freshness tracking and spaced repetition. Backed by Elasticsearch.

Unlike simple key-value memory stores, mcp-brain-tools tracks how old each piece of knowledge is, flags what needs review, and lets agents verify information to keep it fresh — inspired by how spaced repetition helps humans retain knowledge.

Features

• Spaced repetition freshness — each entity has a review interval that doubles on verification (capped at 365 days). Confidence labels (fresh/normal/aging/stale/archival) tell agents what to trust.
• Progressive search — queries return fresh results first, automatically widening to include older data only when needed.
• Observations as entities — each observation gets its own freshness lifecycle, so "build is broken" (1-day review) and "founded in 2015" (365-day review) age independently.
• Memory zones — isolate knowledge by project, team, or domain.
• AI-powered filtering — optional Groq integration scores search results by relevance.
• DRY by design — tool descriptions guide agents not to store what's already in code, git, or docs.

Setup

Prerequisites

• Node.js >= 18
• Docker (for Elasticsearch) or a remote Elasticsearch instance

Install and build

npm install
npm run build

Start Elasticsearch

npm run es:start

Or point to your own instance via `ES_NODE` environment variable.

Configure your MCP client

Add to your Claude Code, Claude Desktop, or other MCP client config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-brain-tools/dist/index.js"],
      "env": {
        "ES_NODE": "http://localhost:9200",
        "GROQ_API_KEY": "your-key-here"
      }
    }
  }
}

`GROQ_API_KEY` is optional — enables AI-powered search filtering and zone relevance scoring.

Install the auto-memory hook (Claude Code only)

The memory hook runs on every user message and automatically injects relevant context — no agent cooperation needed.

Add to `~/.claude/settings.json`:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/mcp-brain-tools/dist/memory-hook.js"
          }
        ]
      }
    ]
  }
}

The hook uses the same `ES_NODE`, `AI_API_KEY`/`GROQ_API_KEY`, `AI_API_BASE`, and `AI_MODEL` env vars (set them in the `env` block of your settings, or export them in your shell profile).

`AI_API_BASE` defaults to Groq's endpoint but accepts any OpenAI-compatible API URL.

How it works

Entities and observations

Entities represent anything worth remembering — people, projects, decisions, facts. Each entity has:

• A name and type
• Spaced repetition fields: `verifiedAt`, `reviewInterval`, `nextReviewAt`
• A confidence label computed from freshness: `1 - (daysSinceVerified / reviewInterval)`

Observations are stored as separate entities linked via `is_observation_of` relations. Each observation has its own review cadence:

Entity: "iaptic-server" (type: Project, reviewInterval: 30 days)
  = 0` — fresh and normal entities
2. `freshness >= -2` — adds aging and stale
3. No filter — adds archival

This keeps results clean while ensuring nothing is permanently lost.

## MCP Tools

| Tool | Description |
|------|-------------|
| `create_entities` | Create entities with optional observations and reviewInterval |
| `update_entities` | Update existing entities |
| `delete_entities` | Delete entities (with optional cascade) |
| `add_observations` | Add observations as separate entities with own freshness |
| `verify_entity` | Confirm entity is still accurate, extend review interval |
| `search_nodes` | Search with progressive freshness filtering |
| `open_nodes` | Get specific entities by name with freshness metadata |
| `get_recent` | Get recently accessed entities |
| `create_relations` | Create relationships between entities |
| `delete_relations` | Remove relationships |
| `inspect_knowledge_graph` | AI-powered entity retrieval with tentative answers |
| `inspect_files` | AI-powered file content inspection |
| `list_zones` | List memory zones (with AI relevance scoring) |
| `create_zone` / `delete_zone` | Manage memory zones |
| `copy_entities` / `move_entities` | Transfer entities between zones |
| `merge_zones` | Merge zones with conflict resolution |
| `zone_stats` | Get entity/relation counts for a zone |
| `mark_important` | Boost entity relevance score |
| `get_time_utc` | Get current UTC time |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ES_NODE` | `http://localhost:9200` | Elasticsearch URL |
| `ES_USERNAME` | — | Elasticsearch username |
| `ES_PASSWORD` | — | Elasticsearch password |
| `GROQ_API_KEY` | — | Groq API key for AI filtering |
| `GROQ_MODELS` | `openai/gpt-oss-120b,llama-3.3-70b-versatile` | Comma-separated model list |
| `KG_INDEX_PREFIX` | `knowledge-graph` | Elasticsearch index prefix |
| `KG_DEFAULT_ZONE` | `default` | Default memory zone |
| `DEBUG` | `false` | Enable debug logging |

## Recommended agent instructions

For agents to actively use the memory server, add something like this to your `CLAUDE.md` (or equivalent instructions file):

Memory

Use MCP Memory (`mcp__memory__*` tools) — a shared knowledge graph across all agents, projects, and computers.

When to SAVE (immediately, before moving on):

• Something you tried didn't work (non-transient) → save what failed and why, so no agent repeats it
• A decision was made (architectural, design, workflow) → save the decision and the reason
• The user corrects you or gives explicit instructions → save the rule
• You learn something non-obvious that took effort to discover → save it

When to SEARCH (before starting, not after failing):

• At the start of every non-trivial task — search before thinking, not after hitting a wall
• About to try an approach that might have been attempted before → search first
• User references something from a past session → search before asking

Rules:

• Skip anything easy to find in code, git log, or docs
• Use the project name as the zone for project-specific knowledge; `default` for general knowledge
• Keep entries short — the AI filters server-side, so be generous rather than selective
• Short `reviewInterval` (e.g. 3–7 days) for volatile facts; longer (30–180) for stable ones

The key insight: agents need explicit trigger-based instructions ("when X, do Y"), not just descriptions of what the tool does.

## Development

npm run build # Compile TypeScript

npm run dev # Watch mode

npm run test:jest # Run Jest tests

npm run es:start # Start Elasticsearch

npm run es:stop # Stop Elasticsearch

npm run es:reset # Wipe data and restart

npm run import # Import from JSON

npm run export # Export to JSON

## License

MIT