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:

Tool	Description
remember	Store architecture decisions, patterns, conventions, bugs, context
recall	Search memories by query, category, tags, or file path
update_memory	Update existing memories when things change
forget	Delete outdated or incorrect memories
project_summary	Get overview of all memories (call at session start)

Memory Categories

Category	Use For
architecture	System design decisions, service boundaries, data flow
pattern	Code patterns: repository, factory, observer, etc.
decision	Why choices were made ("We chose Postgres over MongoDB because...")
dependency	Package choices, version constraints, compatibility notes
convention	Naming rules, file structure, formatting standards
bug	Known bugs, workarounds, things that look wrong but aren't
context	Domain knowledge, business rules, user requirements
todo	Planned improvements, tech debt, future work
relationship	How files/modules connect, dependency graphs

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