CodeMemory for Claude Code

English | 简体中文

Persistent engineering memory for Claude Code.

Store decisions, constraints, failures, and compacted summaries in local SQLite, then bring the right context back into long sessions, complex refactors, and debugging loops.

Star on GitHub · Quick Start · Feature Highlights · Configuration · Tools · Development

CodeMemory is a local-first Claude Code plugin that turns per-session context into durable engineering memory. It stores conversations, summaries, decisions, constraints, failures, and fix attempts in SQLite, then injects the right context back into prompts and risky tool calls.

CodeMemory is intentionally narrow: it is not a general-purpose RAG layer. It is optimized for long Claude Code sessions, complex refactors, and multi-round debugging loops where remembering prior intent matters more than broad document search.

• Claude Code plugin: codememory-plugin
• npm package: codememory-for-claude

Why CodeMemory

CodeMemory is built for three recurring pain points in coding sessions:

1. Long sessions: keep stable requirements and constraints visible after context-window truncation.
2. Complex refactors: preserve design rationale, rejected alternatives, and why the current approach won.
3. Multi-round debugging: recall prior failures and fix attempts before repeating a broken path.

Feature Highlights

• Local-first memory: everything lives in ~/.claude/codememory.db; no external service is required.
• Prompt-time retrieval: every user prompt can pull relevant tasks, constraints, decisions, and failures into additionalContext.
• Prior-failure alerts: before Edit, Write, or Bash, CodeMemory checks whether the target has failed before.
• DAG-based compaction: long history is compacted into leaf and condensed summaries instead of being discarded.
• Structured memory nodes: task, constraint, decision, failure, fix_attempt, and summary nodes with tags, relations, and lifecycle status.
• Fast runtime path: a per-session daemon serves hot lookups over a Unix socket, with a CLI cold-start fallback where needed.
• Debuggable surface area: hooks, tools, and slash commands map cleanly onto the same runtime model.

Architecture Infographic

Quick Start

Prerequisites

• Node.js 22.5 or newer — required, not a recommendation. Storage uses the built-in node:sqlite, which does not exist below 22.5, and the daemon will refuse to start with a version error.
• Claude Code CLI
• jq and curl available on PATH

Contributors: the node:sqlite dependency is deliberate and must not be traded back for a native SQLite binding. Plugin hosts install with --ignore-scripts, which silently skips a native package's build step and leaves every daemon start dying on "Could not locate the bindings file". A built-in has no install step to skip.

Install from Marketplace

Open Claude Code in any project, then run:

/plugin marketplace add harrylettering/CodeMemory
/plugin install codememory-plugin@harrylettering-codememory-marketplace
/reload-plugins

This repository now doubles as its own marketplace through .claude-plugin/marketplace.json, so you can distribute the plugin through Claude Code's standard marketplace flow without a separate catalog repository.

Because the runtime hooks execute compiled JavaScript from dist/, marketplace releases must include committed dist/*.js files in Git.

Install from Source for Development

git clone https://github.com/harrylettering/CodeMemory.git
cd CodeMemory
npm install
npm run build
chmod +x hooks/scripts/*.sh

mkdir -p ~/.claude/plugins
ln -sf "$(pwd)" ~/.claude/plugins/codememory

The repository already contains .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and hooks/hooks.json, so linking the repository root is enough for local development.

Restart Claude Code. On the next SessionStart, CodeMemory will initialize the SQLite database, start its per-session daemon, and begin watching the session transcript.

What Happens After Install

Once installed, CodeMemory runs mostly on its own:

1. SessionStart initializes the database and starts a per-session daemon.
2. The daemon tails the session JSONL so it can ingest model responses as well as hook events.
3. Every UserPromptSubmit can trigger memory-first retrieval and inject relevant context into the prompt.
4. Every PreToolUse checks for prior failures related to the file, command, or symbol being touched.
5. As history grows, M/L-tier messages are compacted into a summary DAG and promoted into reusable memory nodes.

Configuration

All configuration goes through CODEMEMORY_* environment variables resolved in src/db/config.ts. The most useful knobs:

Each model env var is configured independently. If you do not set it explicitly, each one defaults to claude-haiku-4-5-20251001.

For the full environment-variable reference, see docs/CONFIGURATION.md.

Tooling Surface

Default model-callable tools

Debug tools

Enable CODEMEMORY_DEBUG_TOOLS_ENABLED=true to expose:

codememory_grep, codememory_describe, codememory_expand, codememory_expand_query, codememory_memory_pending, codememory_memory_lifecycle

Skills

codememory-mark-decision, codememory-mark-task, codememory-mark-constraint, codememory-context-skill, codememory-summarization-skill

The mark skills post through hooks/scripts/codememory-mark.sh, and the daemon remains the single writer for memory_nodes.

Slash commands

/codememory-status, /codememory-grep, /codememory-describe, /codememory-expand, /codememory-expand-query, /codememory-watch

Documentation

• README.zh-CN.md: Chinese README
• docs/CONFIGURATION.md: full environment-variable reference

Development

Repository Layout

Marketplace Release Checklist

1. Run npm install if dependencies changed.
2. Run npm run plugin:release-check.
3. Commit the updated dist/*.js output together with your source changes.
4. Bump the version in .claude-plugin/plugin.json.
5. Push to GitHub before asking users to install or update from the marketplace.

npm install
npm run build
npm run build:watch
npm test
npm run test:watch
npm run benchmark
npm run benchmark:ci

Useful one-off commands:

npx vitest run test/failure-lookup.test.ts
npx vitest run -t "stitched chain"

Notes:

• The build compiles src/ to dist/.
• Claude Code runtime hooks depend on committed dist/*.js files.
• Hook scripts require jq and curl.
• Prompt-time retrieval depends on the daemon and compiled dist/.
• In offline or CI environments, set CODEMEMORY_COMPACTION_DISABLE_LLM=true.
• If you publish an update, bump the version in .claude-plugin/plugin.json so installed users receive the new release.

Troubleshooting

• No retrieval or failure warnings appear: make sure npm run build has been run, then restart Claude Code so hooks and dist/ are available.
• Daemon does not start: check ~/.claude/codememory-logs/session-start.log and ~/.claude/codememory-logs/daemon.log.
• Offline or CI hangs during compaction: set CODEMEMORY_COMPACTION_DISABLE_LLM=true.
• Need to inspect runtime state: use /codememory-status and review ~/.claude/codememory.db.

License

MIT.