npm package: @howlabs/claude-memory
Description: Project memory compiler for Claude Code — scan repos, generate working context, refresh on change
Author: Claude Project Memory Contributors
Latest version: 0.3.0

# Claude Project Memory

[![npm version](https://badge.fury.io/js/%40howlabs%2Fclaude-memory.svg)](https://www.npmjs.com/package/@howlabs/claude-memory)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/howlabs/claude-project-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/howlabs/claude-project-memory/actions/workflows/ci.yml)

> 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

```bash
# 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

```bash
# 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
```

```bash
claude-project-memory template list
claude-project-memory template apply nextjs-prisma
```

## MCP Server

WebSocket server for real-time context sync:

```bash
claude-project-memory mcp --port 3456
```

**Methods:** `context.get`, `context.refresh`, `ping`

## Configuration

Create `.claude-project-memory.json` or add to `package.json`:

```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

```bash
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/](docs/) for design specs.

## License

MIT