Claude Project Memory

Project memory compiler for Claude Code — scan repositories, generate working context, and refresh when the codebase changes.

What it does

Analyzes your codebase and generates structured markdown files that help Claude Code understand your project:

| File | Purpose | |------|---------| | CLAUDE.md | Project instructions, commands, conventions | | .claude/commands.md | All scripts from package.json | | .claude/architecture.md | High-level project structure | | .claude/risk-map.md | Sensitive areas requiring extra care | | .claude/handoff.md | Session context for handoffs |

Installation

# With Bun (recommended - faster watch mode)
bun install -g @howlabs/claude-memory

# With npm/yarn/pnpm
npm install -g @howlabs/claude-memory

Requirements:

• Bun >= 1.0.0 OR Node.js >= 18.0.0
• Git (for repository scanning)

Quick Start

# Initialize for your project
claude-project-memory init

# Refresh after making changes (preserves manual edits)
claude-project-memory refresh

Common options:

• --dry-run — Preview without writing
• --watch — Auto-refresh on file changes
• --output <dir> — Custom output directory (default: .claude/)

Commands

| Command | Description | |---------|-------------| | init | Generate project memory files | | refresh | Update generated files and preserve the manual section in CLAUDE.md | | doctor | Check for issues | | handoff | Generate context for session transfer | | tag [--major\|--minor\|--patch] | Create git tag with auto-incremented version | | mcp [--port <port>] | Start MCP server for real-time sync | | template list | List available templates | | template apply <name> | Apply a template to your project | | pr-context [--base <branch>] | Generate PR context from git diff | | hooks install\|status\|uninstall | Manage git hooks for auto-refresh | | config [init\|show\|validate] | Manage configuration |

How it works

1. Scans repository structure
2. Detects your stack (Next.js, Vite, React, Vue, etc.)
3. Extracts commands from package.json
4. Identifies risk areas (env files, auth, migrations)
5. Generates markdown files

Manual edits in CLAUDE.md are preserved — add <!-- manual --> after content you want to keep.

Templates

Pre-configured templates for common stacks:

nextjs-prisma | nextjs-trpc | vite-react-testing
vue-nuxt | vue-vite | sveltekit | svelte-vite
remix | astro | astro-react | solid-start | angular
vitest | jest | express | nestjs

claude-project-memory template list
claude-project-memory template apply nextjs-prisma

MCP Server

WebSocket server for real-time context sync:

claude-project-memory mcp --port 3456

Methods: context.get, context.refresh, ping

Configuration

Create .claude-project-memory.json or add to package.json:

{
  "outputDir": ".claude",
  "exclude": ["node_modules", "dist"],
  "generators": {
    "claude": true,
    "commands": true,
    "architecture": true,
    "riskMap": true,
    "handoff": true
  },
  "riskLevel": "medium",
  "mcpPort": 3456,
  "baseBranch": "main"
}

Env vars: CLAUDE_MEMORY_OUTPUT_DIR, CLAUDE_MEMORY_DEBUG, CLAUDE_MEMORY_MCP_PORT, CLAUDE_MEMORY_BASE_BRANCH

Framework Support

Next.js, Vite, React, Vue, Svelte, Solid, Astro, Remix, Nuxt, SvelteKit, Angular

Monorepo Support

Turborepo, pnpm-workspace, npm-workspace, yarn-workspace

Development

git clone https://github.com/howlabs/claude-project-memory
cd claude-project-memory
bun install
bun test
bun run lint
bun run build

See docs/ for design specs.

License

MIT