Brain

This repo has moved to brain-ecosystem. This repository is archived — all development continues in the monorepo. Install via npm install -g @timmeck/brain (unchanged).

Adaptive Error Memory, Code Intelligence & Persistent Context MCP Server for Claude Code

Quick Start

npm install -g @timmeck/brain
brain setup

That's it. One command configures MCP, hooks, and starts the daemon. Brain is now learning from every error you encounter.

What Brain Does

Before Brain: Every session starts from zero

You: Fix this TypeError
Claude: *investigates from scratch, tries 3 approaches, 15 minutes later finds the fix*

Next day, same error in another project:
Claude: *investigates from scratch again*

After Brain: Errors get solved faster every time

You: Fix this TypeError
Claude: *Brain found 3 similar errors. Solution with 94% confidence:
         "Add null check before accessing .length — this pattern occurs
          in array-processing modules across 4 of your projects."*
Fixed in 30 seconds.

Before Brain: Duplicate code everywhere

You: Write a retry wrapper with exponential backoff
Claude: *writes a new implementation*

Meanwhile, you already have 3 retry wrappers across different projects.

After Brain: Code is never rewritten

You: Write a retry wrapper
Claude: *Brain found a reusable module: src/utils/retry.ts (project: api-server)
         Reusability score: 0.92, used in 4 projects, 12 imports*

Before Brain: Errors keep recurring

Week 1: ECONNRESET on API call → fix with retry
Week 2: Same ECONNRESET → debug from scratch
Week 3: Same pattern in different service → no idea it's related

After Brain: Patterns emerge, prevention kicks in

Brain: "⚠ Warning: This code matches antipattern #7 — missing connection
        timeout on HTTP client. This has caused ECONNRESET in 3 projects.
        Suggested fix: add timeout: 5000 to request config."

Features

Error Memory — Track errors, match against known solutions with hybrid search (TF-IDF + vector + synapse boost)
Code Intelligence — Register and discover reusable code modules across all projects
Persistent Memory — Remember preferences, decisions, context, facts, goals, and lessons across sessions (new in v2.2)
Session Tracking — Auto-tracks conversation sessions with goals, summaries, and outcomes (new in v2.2)
Decision History — Record architecture/design decisions with alternatives and rationale (new in v2.2)
Semantic Changelog — Track what changed, why, and how it connects to errors and decisions (new in v2.2)
Task/Goal Tracking — Manage tasks with priorities, subtasks, and full context aggregation (new in v2.2)
Project Doc Index — Auto-index README, CLAUDE.md, package.json, tsconfig.json for instant project context (new in v2.2)
Hebbian Synapse Network — Weighted graph where connections strengthen with use ("neurons that fire together wire together")
Auto Error Detection — PostToolUse hook catches errors in real-time, no manual reporting needed
Auto Context Capture — Hooks auto-capture significant commands as context memories (new in v2.2)
Cross-Project Learning — Solutions from project A help solve errors in project B
Proactive Prevention — Warns before errors occur when code matches known antipatterns
Semantic Search — Local all-MiniLM-L6-v2 embeddings (23MB, no cloud required) for vector similarity
Learning Engine — Extracts patterns, generates rules, detects antipatterns with adaptive thresholds
Research Engine — Automated trend analysis, gap detection, cross-project synergy mapping
Git Integration — Links errors to commits, tracks which changes introduced or fixed bugs
Universal Access — MCP (stdio + HTTP/SSE), REST API, works with Claude Code, Cursor, Windsurf, Cline

Architecture

+------------------+     +------------------+     +------------------+
|   Claude Code    |     |  Cursor/Windsurf |     |  Browser/CI/CD   |
|   (MCP stdio)    |     |  (MCP HTTP/SSE)  |     |  (REST API)      |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         v                        v                        v
+--------+---------+     +--------+---------+     +--------+---------+
|   MCP Server     |     |   MCP HTTP/SSE   |     |    REST API      |
|   (stdio)        |     |   (port 7778)    |     |   (port 7777)    |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         +----------+-------------+------------------------+
                    |
                    v
         +----------+-----------+
         |      BrainCore       |
         |  (Daemon / Services) |
         +----------+-----------+
                    |
    +-------+-------+--------+--------+--------+
    |       |       |        |        |        |
    v       v       v        v        v        v
+---+--+ +--+---+ +-+-----+ +-+----+ +-+----+ +-+--------+
|Error | |Code  | |Synapse| |Git   | |Memory| |Embedding |
|Memory| |Brain | |Network| |Intel | |Brain | |Engine    |
+---+--+ +--+---+ +-+-----+ +-+----+ +-+----+ +-+--------+
    |       |       |        |        |        |
    v       v       v        v        v        v
+---+--+ +--+---+ +-+-----+ +-+----+ +-+----+ +-+--------+
|Learn | |Module| |Hebbian| |Commit| |Tasks | |Vector    |
|Engine| |Score | |Learn  | |Track | |Docs  | |Search    |
+------+ +------+ +-------+ +------+ +------+ +----------+
                    |
                    v
         +----------+-----------+
         |     SQLite (DB)      |
         |  better-sqlite3      |
         +----------------------+

Cross-brain peering via IPC named pipes (\\.\pipe\brain-*, /tmp/brain-*)

Core Components

Component	Purpose
Error Memory	Stores errors with fingerprints, matches new errors against known ones using hybrid search
Solution Tracker	Records solutions with success/fail counts, computes Wilson Score confidence
Code Module Registry	Indexes code across projects — find reusable modules by language, tags, similarity
Memory Brain	Persistent memory for preferences, decisions, context, facts, goals, and lessons (new in v2.2)
Session Tracker	Tracks conversation sessions with goals, summaries, and outcomes (new in v2.2)
Decision History	Records architecture/design decisions with alternatives and rationale (new in v2.2)
Semantic Changelog	Tracks file changes with context: what, why, related errors/decisions (new in v2.2)
Task Manager	Task/goal tracking with priorities, subtasks, and full context aggregation (new in v2.2)
Project Doc Index	Auto-indexes README, CLAUDE.md, package.json for instant project context (new in v2.2)
Synapse Network	Weighted graph connecting all entities. Hebbian rule: "neurons that fire together wire together"
Learning Engine	Extracts patterns from error/solution history, generates preventive rules with adaptive thresholds
Research Engine	Analyzes trends, detects knowledge gaps, finds cross-project synergies
Git Intelligence	Links errors to commits, tracks which changes introduced or fixed bugs
Embedding Engine	Local all-MiniLM-L6-v2 model generates 384-dim vectors for semantic search
REST API	HTTP API exposing all 60+ Brain methods as RESTful endpoints
MCP HTTP Server	SSE transport enabling non-Claude MCP clients (Cursor, Windsurf, etc.)

MCP Tools

These tools are available to Claude Code (and other MCP clients) when Brain is configured:

Tool	Description
Error Brain
`brain_report_error`	Report an error; stores and matches against known errors (hybrid search)
`brain_query_error`	Search for similar errors and solutions
`brain_report_solution`	Report a working solution; Brain learns from it
`brain_report_attempt`	Report a failed attempt; Brain learns what doesn't work
Code Brain
`brain_find_reusable_code`	Search for reusable code modules
`brain_register_code`	Register a code module as reusable
`brain_check_code_similarity`	Check if similar code exists before writing new code
Memory Brain (new in v2.2)
`brain_remember`	Store a memory (preference, decision, context, fact, goal, lesson)
`brain_recall`	Search memories by natural language query
`brain_session_start`	Start a session to track what happens in a conversation
`brain_session_end`	End session with summary and outcome
`brain_session_history`	Recall past sessions ("what was I working on?")
Decision & Changelog (new in v2.2)
`brain_record_decision`	Record architecture/design decision with alternatives
`brain_query_decisions`	Search past decisions ("why did we choose X?")
`brain_record_change`	Record semantic file change (what + why)
`brain_query_changes`	Search changelog ("what changed in file X?")
Task Tracking (new in v2.2)
`brain_add_task`	Add a task/goal with priority and tags
`brain_update_task`	Update task status, add notes
`brain_list_tasks`	List tasks by status/project
`brain_task_context`	Full context: task + related memories, decisions, changes
Project Docs (new in v2.2)
`brain_index_project`	Scan and index project documentation
`brain_query_docs`	Search indexed documentation
`brain_project_context`	Full context: docs + tasks + decisions + changes
Synapse & Research
`brain_explore`	Explore knowledge via spreading activation
`brain_connections`	Find how two concepts are connected
`brain_insights`	Get research insights (trends, gaps, synergies)
`brain_rate_insight`	Rate an insight as useful or not useful
`brain_suggest`	Get suggestions on what to build or improve
Status & Ecosystem
`brain_status`	Current Brain stats (now includes memory and session counts)
`brain_notifications`	Get pending notifications
`brain_ecosystem_status`	Get status of all brains in the ecosystem
`brain_query_peer`	Query another brain in the ecosystem (method + params)
`brain_error_trading_context`	Correlate an error with trading outcomes from Trading Brain

CLI Commands

brain setup              One-command setup: MCP + hooks + daemon
brain start              Start the Brain daemon
brain stop               Stop the daemon
brain status             Show stats (errors, solutions, modules, synapses, insights)
brain doctor             Health check: daemon, DB, MCP, hooks
brain projects           List all imported projects with module counts
brain query <text>       Search for errors and solutions
brain modules            List registered code modules
brain insights           Show research insights
brain network            Explore the synapse network
brain learn              Trigger a learning cycle manually
brain explain <id>       Full error report: solutions, chains, rules, insights
brain config             View and manage Brain configuration
brain export             Export Brain data as JSON
brain import <dir>       Import a project directory into Brain
brain dashboard          Generate interactive HTML dashboard (--live for SSE)
brain peers              Show status of peer brains in the ecosystem

REST API

Brain includes a full REST API on port 7777 (default).

Generic RPC Endpoint

# Call any Brain method
curl -X POST http://localhost:7777/api/v1/rpc \
  -H "Content-Type: application/json" \
  -d '{"method": "analytics.summary", "params": {}}'

# Batch multiple calls
curl -X POST http://localhost:7777/api/v1/rpc \
  -H "Content-Type: application/json" \
  -d '[
    {"id": 1, "method": "analytics.summary", "params": {}},
    {"id": 2, "method": "synapse.stats", "params": {}}
  ]'

RESTful Endpoints

# Errors
GET    /api/v1/errors                    # Query errors
POST   /api/v1/errors                    # Report error
GET    /api/v1/errors/:id                # Get error by ID
GET    /api/v1/errors/:id/match          # Find similar errors (hybrid search)
GET    /api/v1/errors/:id/chain          # Get error chain

# Solutions
POST   /api/v1/solutions                 # Report solution
GET    /api/v1/solutions?errorId=N       # Find solutions for error
GET    /api/v1/solutions/efficiency       # Efficiency analysis

# Code
POST   /api/v1/code/analyze              # Analyze and register code
POST   /api/v1/code/find                 # Find reusable code
POST   /api/v1/code/similarity           # Check code similarity
GET    /api/v1/code/modules              # List modules

# Analytics
GET    /api/v1/analytics/summary         # Brain summary
GET    /api/v1/analytics/health          # Health score
GET    /api/v1/analytics/timeline        # Error timeline
GET    /api/v1/analytics/explain/:id     # Full error explanation

# Git
GET    /api/v1/git/context               # Current git info
POST   /api/v1/git/link-error            # Link error to commit

# Meta
GET    /api/v1/health                    # API health check
GET    /api/v1/methods                   # List all 60+ available methods

Authentication

BRAIN_API_KEY=your-secret-key brain start
curl -H "X-API-Key: your-secret-key" http://localhost:7777/api/v1/analytics/summary

Setup with Cursor / Windsurf / Cline / Continue

Brain supports MCP over HTTP with SSE transport:

{
  "brain": {
    "url": "http://localhost:7778/sse"
  }
}

Make sure the Brain daemon is running (brain start).

Configuration

Env Variable	Default	Description
`BRAIN_DATA_DIR`	`~/.brain`	Data directory
`BRAIN_LOG_LEVEL`	`info`	Log level
`BRAIN_API_PORT`	`7777`	REST API port
`BRAIN_API_KEY`	—	API authentication key
`BRAIN_MCP_HTTP_PORT`	`7778`	MCP HTTP/SSE port
`BRAIN_API_ENABLED`	`true`	Enable REST API
`BRAIN_MCP_HTTP_ENABLED`	`true`	Enable MCP HTTP
`BRAIN_EMBEDDINGS_ENABLED`	`true`	Enable local embeddings
`BRAIN_EMBEDDINGS_MODEL`	`Xenova/all-MiniLM-L6-v2`	Embedding model

How It Learns

Error Reported — Claude encounters an error (hook catches it automatically or via brain_report_error)
Context Enriched — Brain captures task context, working directory, command, git branch, and diff
Hybrid Matched — Error is compared against known errors using TF-IDF signals, vector embeddings, and synapse proximity
Solution Found — When the error is fixed, brain_report_solution records the fix
Synapses Form — Brain creates weighted connections: error ↔ solution, error ↔ code module, module ↔ dependency
Confidence Updates — Wilson Score Interval computes conservative confidence from success/fail history
Patterns Emerge — Learning engine extracts recurring patterns with adaptive thresholds
Research Runs — Background analysis finds trends, gaps, and cross-project synergies
Embeddings Computed — Background sweep generates vector embeddings for semantic search
Next Time — When a similar error appears, Brain instantly suggests the proven solution — even from other projects

How It Remembers (v2.2)

Brain now maintains persistent context across sessions:

Session Auto-Start — PreToolUse hook auto-starts a session per working directory
Context Captured — Significant commands (npm, git, test, build, deploy) are auto-remembered as context
Preferences Stored — User preferences (test framework, code style, tools) are stored with key-based upsert
Decisions Recorded — Architecture decisions with alternatives and rationale for "why did we choose X?"
Changes Tracked — Semantic changelog links file changes to errors and decisions
Tasks Managed — Goals and tasks with priorities, subtasks, and full context aggregation
Docs Indexed — README, CLAUDE.md, package.json indexed for instant project context
Everything Connected — All new entities join the synapse network, enabling cross-entity discovery

Brain Ecosystem

Brain is part of the Brain Ecosystem — a monorepo of MCP servers that give Claude Code persistent, self-learning memory.

Brain	Purpose	Ports
Brain v2.2.1	Error memory, code intelligence & persistent context	7777 / 7778
Trading Brain v1.3.2	Adaptive trading intelligence with memory & sessions	7779 / 7780
Marketing Brain v0.5.2	Content strategy & engagement with memory & sessions	7781 / 7782 / 7783
Brain Core v1.6.1	Shared infrastructure (IPC, MCP, REST, CLI, math, synapses, memory)	—
Brain Hub	Ecosystem landing page	—

All packages live in the brain-ecosystem monorepo with npm workspaces. Brain Core provides shared infrastructure (IPC, MCP, REST API, CLI, math, synapse algorithms, memory types) used by all brains, eliminating ~2,800 lines of duplicated code.

Cross-Brain Communication

Brains discover and query each other at runtime via IPC named pipes. Use brain peers to see online peers, or the brain_query_peer / brain_ecosystem_status MCP tools to access peer data from Claude Code. Brains also push event notifications to each other — when Brain reports an error, Trading Brain and Marketing Brain are notified automatically.

Tech Stack

TypeScript — Full type safety, ES2022 target, ESM modules
better-sqlite3 — Fast, embedded, synchronous database
MCP SDK — Model Context Protocol integration (stdio + HTTP/SSE transports)
@huggingface/transformers — Local ONNX-based sentence embeddings (all-MiniLM-L6-v2)
Commander — CLI framework
Chalk — Colored terminal output
Winston — Structured logging
Vitest — Testing

Support

If Brain helps you, consider giving it a star — it helps others discover the project and keeps development going.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github		.github
assets		assets
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
BRAIN_PLAN.md		BRAIN_PLAN.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
gen_avatar.py		gen_avatar.py
package-lock.json		package-lock.json
package.json		package.json
reddit_post.md		reddit_post.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Brain

Quick Start

What Brain Does

Before Brain: Every session starts from zero

After Brain: Errors get solved faster every time

Before Brain: Duplicate code everywhere

After Brain: Code is never rewritten

Before Brain: Errors keep recurring

After Brain: Patterns emerge, prevention kicks in

Features

Architecture

Core Components

MCP Tools

CLI Commands

REST API

Generic RPC Endpoint

RESTful Endpoints

Authentication

Setup with Cursor / Windsurf / Cline / Continue

Configuration

How It Learns

How It Remembers (v2.2)

Brain Ecosystem

Cross-Brain Communication

Tech Stack

Support

License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Brain

Quick Start

What Brain Does

Before Brain: Every session starts from zero

After Brain: Errors get solved faster every time

Before Brain: Duplicate code everywhere

After Brain: Code is never rewritten

Before Brain: Errors keep recurring

After Brain: Patterns emerge, prevention kicks in

Features

Architecture

Core Components

MCP Tools

CLI Commands

REST API

Generic RPC Endpoint

RESTful Endpoints

Authentication

Setup with Cursor / Windsurf / Cline / Continue

Configuration

How It Learns

How It Remembers (v2.2)

Brain Ecosystem

Cross-Brain Communication

Tech Stack

Support

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages