Why

AI coding assistants start every session with zero knowledge of your project. They re-read files, re-discover your stack, and re-learn your conventions. On large codebases this burns through context windows, wastes time, and produces inconsistent suggestions.

codebase-memory fixes this. It performs a one-time deep analysis of your project and writes structured context files that your AI tool loads automatically at session start. The result: every session begins exactly where the last one left off.

Before                              After
──────                              ─────
Session 1  scan 200 files  slow     Session 1  analyze once     one-time
Session 2  scan 200 files  slow     Session 2  load context     instant
Session 3  scan 200 files  slow     Session 3  load context     instant

Install

npm install -g codebase-memory

Quick start

Option A — Fully automatic (Claude Code)

codebase-memory setup

Installs invisible hooks. New projects are auto-analyzed on first use, changes are tracked during work, and memory is updated when the session ends. Nothing else to do.

Option B — Any AI tool

cd your-project
codebase-memory analyze

Generates context files for every supported tool in one pass.

Supported tools

A single analyze creates the correct file for each tool:

| Generated file | Tool | Loaded | |:--|:--|:--| | CLAUDE.md + .claude/rules/ | Claude Code | Automatically | | .cursorrules | Cursor | Automatically | | .github/copilot-instructions.md | GitHub Copilot | Automatically | | .windsurfrules | Windsurf | Automatically | | .clinerules | Cline | Automatically | | CONVENTIONS.md | Aider | Via .aider.conf.yml | | .roomodes | Roo Code | Automatically |

What it generates

project/
├── CLAUDE.md                        Claude Code context
├── .cursorrules                     Cursor context
├── .windsurfrules                   Windsurf context
├── .clinerules                      Cline context
├── .roomodes                        Roo Code context
├── CONVENTIONS.md                   Aider context
├── .github/
│   └── copilot-instructions.md      GitHub Copilot context
└── .claude/
    └── rules/
        ├── architecture.md          Folder map, entry points, data flow
        ├── stack.md                 Languages, frameworks, versions, commands
        ├── modules.md               Every module and its responsibility
        ├── models.md                Database schemas, types, entities
        ├── api.md                   Routes and endpoints
        ├── conventions.md           Naming patterns, error handling, testing
        ├── gotchas.md               Quirks, workarounds, do-not-touch files
        └── changelog.md             Auto-updated change log

Detection coverage

| Category | What's detected | |:--|:--| | Languages | JavaScript, TypeScript, Python, Go, Rust, Ruby, Java, Kotlin | | Frameworks | Next.js, React, Vue, Svelte, Express, FastAPI, Django, Flask, NestJS, Remix, Astro, Nuxt, SvelteKit, Hono, Koa, Fastify, Angular, Gatsby, Electron + more | | Databases | PostgreSQL, MySQL, SQLite, MongoDB, Redis | | ORMs | Prisma, Drizzle, TypeORM, Sequelize, Mongoose, SQLAlchemy | | Package managers | npm, pnpm, yarn, bun, pip, uv, pipenv | | Testing | Vitest, Jest, Mocha, pytest, Playwright, Cypress | | Build tools | Vite, webpack, esbuild, Rollup, Turborepo | | Linting | ESLint, Prettier, Biome | | State management | Zustand, Redux, TanStack Query | | Infrastructure | Docker, docker-compose | | Structure | Entry points, route files, model files, API surfaces, naming conventions |

How automation works

When you run codebase-memory setup, three Claude Code hooks are installed globally:

Session start     PreToolUse hook checks for CLAUDE.md
                  ├── missing → analyzes project in background
                  └── present → skips instantly

During work       PostToolUse hook fires on Write / Edit
                  └── appends file path + timestamp to changelog.md

Session end       Stop hook fires
                  └── runs incremental update (new modules, routes, models)

The session-start check uses a temp marker per project directory. After the first tool call it exits in microseconds.

For tools other than Claude Code, run codebase-memory analyze once per project or codebase-memory update after significant changes.

Change tracking

Every edit made by the AI is recorded:

## 2026-04-14 — Initial analysis
- Full codebase analyzed and memory files written
- 12 modules mapped, 8 endpoints documented, 5 models captured

## 2026-04-14
- `src/routes/payments.ts` — Write at 14:30
- `src/models/invoice.ts` — Edit at 14:35

### Session ended at 15:00
**Recent commits:**
  a1b2c3d Add payment processing endpoint
  d4e5f6g Update invoice model

CLI reference

codebase-memory <command> [options]

Commands:
  setup              Install global Claude Code hooks (one-time)
  analyze [dir]      Full analysis + generate context for all IDEs
  update  [dir]      Incremental update — append only what changed
  restore [dir]      Print project summary from memory files
  teardown           Remove global hooks

Aliases:
  s → setup    a → analyze    u → update    r → restore

Comparison

| | codebase-memory | Manual rules files | No context | |:--|:-:|:-:|:-:| | Auto-generates from codebase | Yes | — | — | | Detects stack and frameworks | Yes | — | — | | Maps modules, routes, models | Yes | — | — | | Tracks changes automatically | Yes | — | — | | Updates memory on session end | Yes | — | — | | Covers 7 AI tools at once | Yes | 1 | — | | Time to set up | 30 seconds | Hours | — |

FAQ

Uninstall

codebase-memory teardown             # remove hooks
npm uninstall -g codebase-memory     # remove package

Remove memory from a specific project:

rm -f CLAUDE.md .cursorrules .windsurfrules .clinerules .roomodes CONVENTIONS.md
rm -rf .claude/rules/ .github/copilot-instructions.md

Contributing

Issues and pull requests are welcome.

To add support for a new AI tool, see src/utils/ide-generator.js — the architecture is designed for easy extension.