Codebrain

🧠 Codebrain

Persistent context index for AI coding agents

Give your AI coding assistant memory. Codebrain indexes your Claude Code conversations, stakeholder meetings, and documentation into a searchable knowledge base that persists across sessions.

The Problem

Claude Code doesn't remember. Every session starts blank.

• You re-explain your architecture
• It re-discovers edge cases you already solved
• It makes decisions that contradict past choices
• It doesn't know what stakeholders said in that meeting last week

You are the memory. That doesn't scale.

The Solution

Codebrain extracts and indexes signals from your project history:

| Signal Type | What It Captures | |-------------|------------------| | decision | Architectural choices made — don't revisit | | pattern | Established approaches — follow these | | gotcha | Non-obvious pitfalls — watch out | | constraint | Hard limitations — can't violate | | requirement | What must be built — from stakeholders | | edge_case | Unusual scenarios — preserve handling | | failed | Approaches that didn't work — don't repeat | | debt | Known compromises — revisit later |

When Claude Code starts a session, it queries Codebrain for relevant context. No more re-explaining. No more regressions.

Quick Start

# Install
npm install -g @codebrain/cli

# Initialize in your project
cd your-project
codebrain init

# Index your Claude Code history
codebrain index

# Start the MCP server (for Claude Code integration)
codebrain serve

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "codebrain": {
      "command": "codebrain",
      "args": ["serve"],
      "cwd": "/path/to/your-project"
    }
  }
}

Configuration

Create codebrain.config.ts in your project root:

import { defineConfig } from '@codebrain/core';

export default defineConfig({
  name: 'my-project',
  
  sources: {
    // Index Claude Code conversations
    claudeCode: {
      projectPath: '~/.claude/projects/my-project',
    },
    
    // Index meeting transcripts
    meetings: {
      path: './meetings',
      format: 'gemini',  // or 'otter', 'plain'
    },
    
    // Index git history
    git: {
      includeCommits: true,
      includePRs: true,
    },
  },
  
  // Define your project's scopes
  scopes: {
    autoDetect: {
      fromRoutes: 'src/app',
      fromFeatures: 'src/features',
    },
    manual: [
      {
        name: 'auth',
        patterns: ['src/**/auth/**', 'src/**/login/**'],
        keywords: ['authentication', 'login', 'session'],
      },
    ],
  },
  
  // Freshness rules
  freshness: {
    decayRate: 0.98,              // 2% confidence decay per day
    codeChangeInvalidates: true,  // Mark stale when code changes
    maxAgeBeforeRevalidation: 30, // Days
  },
});

CLI Commands

# Initialize codebrain in a project
codebrain init

# Index all configured sources
codebrain index

# Index specific source
codebrain index --source=claudeCode
codebrain index --source=meetings

# Search the knowledge base
codebrain search "tenant isolation"
codebrain search --scope=dashboard --type=decision

# Get context for a scope
codebrain context dashboard

# Show index status
codebrain status

# Start MCP server
codebrain serve

# Export signals (backup)
codebrain export --output=signals.json

# Validate signals (check freshness)
codebrain validate

MCP Tools

When connected via MCP, Claude Code gets these tools:

codebrain_search

Search for relevant signals by scope, type, or natural language query.

codebrain_context

Get formatted context for a scope — requirements, constraints, patterns, gotchas — ready to use.

codebrain_validate

Check if planned changes violate known constraints or regress edge cases.

codebrain_record

Record a new signal discovered during the session (decision, gotcha, pattern, etc.).

codebrain_status

Get index stats and signals needing attention.

How It Works

┌─────────────────────────────────────────────────────────┐
│                      SOURCES                            │
│                                                         │
│  Claude Code JSONL ──┐                                 │
│  Meeting transcripts ─┼──► PARSERS ──► EXTRACTION     │
│  Git commits ─────────┘                    │           │
│                                            ▼           │
├─────────────────────────────────────────────────────────┤
│                      STORAGE                            │
│                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌───────────┐  │
│  │   SIGNALS   │◄──►│    GRAPH    │◄──►│  VECTORS  │  │
│  │  (SQLite)   │    │ (relations) │    │ (search)  │  │
│  └─────────────┘    └─────────────┘    └───────────┘  │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                     RETRIEVAL                           │
│                                                         │
│  Query ──► Scope Match ──► Freshness Filter ──► Rank   │
│                                            │           │
│                                            ▼           │
│                                    Formatted Context   │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                    INTERFACES                           │
│                                                         │
│  ┌─────────────┐    ┌─────────────┐                    │
│  │ MCP SERVER  │    │     CLI     │                    │
│  │(Claude Code)│    │             │                    │
│  └─────────────┘    └─────────────┘                    │
│                                                         │
└─────────────────────────────────────────────────────────┘

Signal Extraction

Codebrain uses Claude to extract signals from unstructured content:

1. Parse source files (JSONL, transcripts, commits)
2. Chunk into processable segments
3. Extract signals using LLM with specialized prompts
4. Link signals by scope and relationships
5. Index for fast retrieval

Freshness Tracking

Signals decay over time and can become stale:

• Confidence decay: Decreases daily without validation
• Code drift: Signals linked to changed code get flagged
• Supersession: New signals can replace old ones
• Validation: QA runs and human review update confidence

Project Structure

codebrain/
├── packages/
│   ├── core/           # Types, config, storage interface
│   ├── parsers/        # Source parsers (Claude Code, meetings, git)
│   ├── extraction/     # LLM signal extraction
│   ├── mcp-server/     # MCP server for Claude Code
│   └── cli/            # Command line interface
├── examples/
│   ├── minimal/        # Basic setup
│   └── complex-app/    # Full configuration
└── docs/

Roadmap

• [x] Core types and interfaces
• [x] Claude Code JSONL parser
• [x] Meeting transcript parser
• [x] MCP server structure
• [ ] SQLite storage implementation
• [ ] Signal extraction with Claude
• [ ] Vector search integration
• [ ] Git history parser
• [ ] CLI implementation
• [ ] Freshness engine
• [ ] Graph relationships
• [ ] Web UI for review

Contributing

Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TerminalGravity
• Source: TerminalGravity/codebrain
• License: MIT

Install and usage instructions live in the source repository linked above.