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.

• 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.

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

npm install
npm run build

npm run es:start

Or point to your own instance via ES_NODE environment variable.

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.

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)
  <- "iaptic-server: uses TypeScript" (reviewInterval: 180 days)
  <- "iaptic-server: migration in progress" (reviewInterval: 7 days)

1. Entity created — confidence: "fresh", default review in 7 days
2. Review date passes — confidence: "aging", needsReview: true
3. Agent verifies (via verify_entity) — interval doubles, confidence resets to fresh
4. Long overdue — confidence: "stale" then "archival", excluded from default search

When searching, the server uses three passes:

1. freshness >= 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.

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

MIT