Codebase Memory

Your AI agent forgets everything between sessions. This MCP server fixes that.

You: "What architecture pattern does this project use?"

Without codebase-memory:
  AI: "I'd need to look through the codebase to determine that."

With codebase-memory:
  AI: "This project uses a hexagonal architecture with ports and adapters.
       The decision was made in March 2026 to improve testability.
       Related files: src/ports/, src/adapters/, src/domain/"

The Problem

AI coding agents (Cursor, Claude, Copilot) lose all context between sessions:

• Architecture decisions get forgotten and re-asked
• Code patterns get violated because the AI doesn't know your conventions
• Bug workarounds get re-introduced after being fixed
• Every session starts from zero

codebase-memory gives your AI persistent memory through the Model Context Protocol (MCP).

Quick Start

# Install
npm install -g codebase-memory

# Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json)
{
  "mcpServers": {
    "codebase-memory": {
      "command": "npx",
      "args": ["codebase-memory"]
    }
  }
}

That's it. Your AI agent now has 5 memory tools:

Memory Categories

How It Works

1. AI stores knowledge — As your agent learns about the codebase, it calls remember to save important information
2. Persisted in SQLite — Memories are stored locally in .codebase-memory/memory.db
3. Retrieved on demand — When the agent needs context, it calls recall with a search query
4. Full-text search — SQLite FTS5 enables fast, relevant search across all memories
5. Importance scoring — High-importance memories surface first

Example Workflow

Session 1 (you're setting up the project):
  AI remembers:
  - "architecture: Monorepo with turborepo, apps/ for services, packages/ for shared"
  - "convention: All API routes use zod validation middleware"
  - "decision: Chose Drizzle ORM over Prisma for edge runtime support"
  - "bug: Don't use Date objects in API responses, use ISO strings (timezone issues)"

Session 2 (next day, different task):
  AI calls project_summary -> instantly knows the project structure
  AI calls recall({query: "API validation"}) -> knows to use zod middleware
  AI calls recall({filePath: "src/api/"}) -> gets all API-related memories
  -> Writes code that follows all your established patterns

Configuration

Claude Desktop

{
  "mcpServers": {
    "codebase-memory": {
      "command": "npx",
      "args": ["codebase-memory"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codebase-memory": {
      "command": "npx",
      "args": ["codebase-memory"]
    }
  }
}

Custom Database Location

{
  "mcpServers": {
    "codebase-memory": {
      "command": "npx",
      "args": ["codebase-memory", "--db", "/path/to/memory.db"]
    }
  }
}

Programmatic API

import { MemoryDatabase } from 'codebase-memory';

const db = new MemoryDatabase({ path: './memory.db' });

// Store a memory
const entry = db.create({
  category: 'architecture',
  title: 'Event-driven messaging',
  content: 'Services communicate via RabbitMQ. Orders service publishes OrderCreated events.',
  tags: ['messaging', 'rabbitmq'],
  filePaths: ['src/events/', 'src/services/orders/'],
  importance: 9,
});

// Search memories
const results = db.query({
  query: 'messaging',
  category: 'architecture',
  minImportance: 7,
});

// Get project overview
const summary = db.getSummary();
console.log(`Total memories: ${summary.totalMemories}`);
console.log(`Top tags: ${summary.topTags.map(t => t.tag).join(', ')}`);

db.close();

Data Storage

• Location: .codebase-memory/memory.db (in your project root)
• Format: SQLite with FTS5 full-text search
• Size: Typically under 1MB for thousands of memories
• Backup: Just copy the .db file
• Git: Add .codebase-memory/ to .gitignore (per-developer memories) or commit it (shared team knowledge)

CLI Options

codebase-memory [options]

  --db <path>       SQLite database path (default: .codebase-memory/memory.db)
  --project <path>  Project root directory (default: cwd)
  --version         Show version
  --help            Show help

License

MIT