[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11673":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":25,"discoverSource":26},11673,"CodeMemory","harrylettering\u002FCodeMemory","harrylettering","A memory layer for Claude Code","",null,"TypeScript",161,15,6,2,0,106,50.61,false,"main",[],"2026-06-12 04:00:55","# CodeMemory for Claude Code\n\n[English](.\u002FREADME.md) | [简体中文](.\u002FREADME.zh-CN.md)\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Persistent engineering memory for Claude Code.\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  Store decisions, constraints, failures, and compacted summaries in local SQLite, then bring the right context back into long sessions, complex refactors, and debugging loops.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fharrylettering\u002FCodeMemory\u002Fstargazers\">Star on GitHub\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#feature-highlights\">Feature Highlights\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#configuration\">Configuration\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#tooling-surface\">Tools\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#development\">Development\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fharrylettering\u002FCodeMemory\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fharrylettering\u002FCodeMemory?style=flat-square\" alt=\"GitHub stars\" \u002F>\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude%20Code-Plugin-black\" alt=\"Claude Code Plugin\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSQLite-Local%20First-003B57\" alt=\"SQLite Local First\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPersistent-Memory-1f6feb\" alt=\"Persistent Memory\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue\" alt=\"MIT License\" \u002F>\n\u003C\u002Fp>\n\nCodeMemory 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.\n\nCodeMemory 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.\n\n- Claude Code plugin: `codememory-plugin`\n- npm package: `codememory-for-claude`\n\n## Why CodeMemory\n\nCodeMemory is built for three recurring pain points in coding sessions:\n\n1. **Long sessions**: keep stable requirements and constraints visible after context-window truncation.\n2. **Complex refactors**: preserve design rationale, rejected alternatives, and why the current approach won.\n3. **Multi-round debugging**: recall prior failures and fix attempts before repeating a broken path.\n\n## Feature Highlights\n\n- **Local-first memory**: everything lives in `~\u002F.claude\u002Fcodememory.db`; no external service is required.\n- **Prompt-time retrieval**: every user prompt can pull relevant tasks, constraints, decisions, and failures into `additionalContext`.\n- **Prior-failure alerts**: before `Edit`, `Write`, or `Bash`, CodeMemory checks whether the target has failed before.\n- **DAG-based compaction**: long history is compacted into leaf and condensed summaries instead of being discarded.\n- **Structured memory nodes**: `task`, `constraint`, `decision`, `failure`, `fix_attempt`, and `summary` nodes with tags, relations, and lifecycle status.\n- **Fast runtime path**: a per-session daemon serves hot lookups over a Unix socket, with a CLI cold-start fallback where needed.\n- **Debuggable surface area**: hooks, tools, and slash commands map cleanly onto the same runtime model.\n\n## Architecture Infographic\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fcodememory-architecture-en.png\" alt=\"CodeMemory Architecture Infographic\" width=\"1200\" \u002F>\n\u003C\u002Fp>\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18 or newer\n- Claude Code CLI\n- `jq` and `curl` available on `PATH`\n\n### Install from Marketplace\n\nOpen Claude Code in any project, then run:\n\n```text\n\u002Fplugin marketplace add harrylettering\u002FCodeMemory\n\u002Fplugin install codememory-plugin@harrylettering-codememory-marketplace\n\u002Freload-plugins\n```\n\nThis repository now doubles as its own marketplace through [`.claude-plugin\u002Fmarketplace.json`](.\u002F.claude-plugin\u002Fmarketplace.json), so you can distribute the plugin through Claude Code's standard marketplace flow without a separate catalog repository.\n\nBecause the runtime hooks execute compiled JavaScript from `dist\u002F`, marketplace releases must include committed `dist\u002F*.js` files in Git.\n\n### Install from Source for Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fharrylettering\u002FCodeMemory.git\ncd CodeMemory\nnpm install\nnpm run build\nchmod +x hooks\u002Fscripts\u002F*.sh\n\nmkdir -p ~\u002F.claude\u002Fplugins\nln -sf \"$(pwd)\" ~\u002F.claude\u002Fplugins\u002Fcodememory\n```\n\nThe repository already contains `.claude-plugin\u002Fplugin.json`, `.claude-plugin\u002Fmarketplace.json`, and `hooks\u002Fhooks.json`, so linking the repository root is enough for local development.\n\nRestart Claude Code. On the next `SessionStart`, CodeMemory will initialize the SQLite database, start its per-session daemon, and begin watching the session transcript.\n\n## What Happens After Install\n\nOnce installed, CodeMemory runs mostly on its own:\n\n1. `SessionStart` initializes the database and starts a per-session daemon.\n2. The daemon tails the session JSONL so it can ingest model responses as well as hook events.\n3. Every `UserPromptSubmit` can trigger memory-first retrieval and inject relevant context into the prompt.\n4. Every `PreToolUse` checks for prior failures related to the file, command, or symbol being touched.\n5. As history grows, M\u002FL-tier messages are compacted into a summary DAG and promoted into reusable memory nodes.\n\n## Configuration\n\nAll configuration goes through `CODEMEMORY_*` environment variables resolved in [`src\u002Fdb\u002Fconfig.ts`](.\u002Fsrc\u002Fdb\u002Fconfig.ts). The most useful knobs:\n\nEach model env var is configured independently. If you do not set it explicitly, each one defaults to `claude-haiku-4-5-20251001`.\n\n| Variable | Default | Description |\n|---|---|---|\n| `CODEMEMORY_ENABLED` | `true` | Global on\u002Foff switch. |\n| `CODEMEMORY_DATABASE_PATH` | `~\u002F.claude\u002Fcodememory.db` | SQLite database location. |\n| `CODEMEMORY_WORKSPACE_ROOT` | daemon's `cwd` at start | Root used to qualify file tags across repositories. |\n| `CODEMEMORY_DEBUG_TOOLS_ENABLED` | `false` | Expose grep\u002Fdescribe\u002Fexpand\u002Flifecycle admin tools to the model. |\n| `CODEMEMORY_COMPACTION_ENABLED` | `true` | Enable async compaction. |\n| `CODEMEMORY_COMPACTION_TOKEN_THRESHOLD` | `30000` | Uncompacted M\u002FL token budget that triggers compaction. |\n| `CODEMEMORY_COMPACTION_FRESH_TAIL_COUNT` | `20` | Most-recent messages protected from compaction. |\n| `CODEMEMORY_COMPACTION_DISABLE_LLM` | `false` | Skip `claude --print` and use truncation fallback. Required offline \u002F in CI. |\n| `CODEMEMORY_EXPANSION_MODEL` | `claude-haiku-4-5-20251001` | Model used by `codememory_expand` and `codememory_expand_query`. |\n| `CODEMEMORY_QUERY_PLANNER_MODEL` | `claude-haiku-4-5-20251001` | Model used by the optional query planner. |\n| `CODEMEMORY_COMPACTION_MODEL` | `claude-haiku-4-5-20251001` | Model used for compaction. |\n| `CODEMEMORY_AUTO_SUPERSEDE_MODEL` | `claude-haiku-4-5-20251001` | Model used by the optional auto-supersede judge. |\n| `CODEMEMORY_QUERY_PLANNER_ENABLED` | `false` | Enable the optional LLM planner after weak fast-path retrieval. |\n| `CODEMEMORY_AUTO_SUPERSEDE_VIA_LLM` | `false` | Auto-detect implicit decision supersedes within a conversation. |\n| `CODEMEMORY_EXPLORED_TARGET_WINDOW_MS` | `1800000` (30 min) | Repeat exploration of the same Read\u002FGrep\u002FGlob target inside this window decays L → N. |\n\nFor the full environment-variable reference, see [docs\u002FCONFIGURATION.md](.\u002Fdocs\u002FCONFIGURATION.md).\n\n## Tooling Surface\n\n### Default model-callable tools\n\n| Tool | Purpose |\n|---|---|\n| `codememory_check_prior_failures` | Ask whether a file, command, or symbol has failed before. |\n| `codememory_mark_decision` | Persist a meaningful technical decision as a `decision` node. |\n| `codememory_mark_requirement` | Persist a hard requirement or stable constraint. |\n| `codememory_compact` | Force compaction for the current conversation. |\n\n### Debug tools\n\nEnable `CODEMEMORY_DEBUG_TOOLS_ENABLED=true` to expose:\n\n`codememory_grep`, `codememory_describe`, `codememory_expand`, `codememory_expand_query`, `codememory_memory_pending`, `codememory_memory_lifecycle`\n\n### Skills\n\n`codememory-mark-decision`, `codememory-mark-task`, `codememory-mark-constraint`, `codememory-context-skill`, `codememory-summarization-skill`\n\nThe mark skills post through `hooks\u002Fscripts\u002Fcodememory-mark.sh`, and the daemon remains the single writer for `memory_nodes`.\n\n### Slash commands\n\n`\u002Fcodememory-status`, `\u002Fcodememory-grep`, `\u002Fcodememory-describe`, `\u002Fcodememory-expand`, `\u002Fcodememory-expand-query`, `\u002Fcodememory-watch`\n\n## Documentation\n\n- [README.zh-CN.md](.\u002FREADME.zh-CN.md): Chinese README\n- [docs\u002FCONFIGURATION.md](.\u002Fdocs\u002FCONFIGURATION.md): full environment-variable reference\n\n## Development\n\n### Repository Layout\n\n| Path | Purpose |\n|---|---|\n| `src\u002F` | Core runtime: retrieval, compaction, stores, hooks runtime, and plugin activation. |\n| `hooks\u002F` | Claude Code hook definitions and shell entrypoints. |\n| `commands\u002F` | Slash-command descriptions such as `\u002Fcodememory-status` and `\u002Fcodememory-watch`. |\n| `skills\u002F` | Skills for marking decisions, tasks, and constraints from the model side. |\n| `docs\u002F` | User-facing configuration reference in English and Chinese. |\n| `test\u002F` | Automated tests for retrieval, lifecycle, failure lookup, compaction, and tools. |\n| `benchmark\u002F` | Latency benchmark for the lookup path. |\n\n### Marketplace Release Checklist\n\n1. Run `npm install` if dependencies changed.\n2. Run `npm run plugin:release-check`.\n3. Commit the updated `dist\u002F*.js` output together with your source changes.\n4. Bump the version in [`.claude-plugin\u002Fplugin.json`](.\u002F.claude-plugin\u002Fplugin.json).\n5. Push to GitHub before asking users to install or update from the marketplace.\n\n```bash\nnpm install\nnpm run build\nnpm run build:watch\nnpm test\nnpm run test:watch\nnpm run benchmark\nnpm run benchmark:ci\n```\n\nUseful one-off commands:\n\n```bash\nnpx vitest run test\u002Ffailure-lookup.test.ts\nnpx vitest run -t \"stitched chain\"\n```\n\nNotes:\n\n- The build compiles `src\u002F` to `dist\u002F`.\n- Claude Code runtime hooks depend on committed `dist\u002F*.js` files.\n- Hook scripts require `jq` and `curl`.\n- Prompt-time retrieval depends on the daemon and compiled `dist\u002F`.\n- In offline or CI environments, set `CODEMEMORY_COMPACTION_DISABLE_LLM=true`.\n- If you publish an update, bump the version in [`.claude-plugin\u002Fplugin.json`](.\u002F.claude-plugin\u002Fplugin.json) so installed users receive the new release.\n\n## Troubleshooting\n\n- **No retrieval or failure warnings appear**: make sure `npm run build` has been run, then restart Claude Code so hooks and `dist\u002F` are available.\n- **Daemon does not start**: check `~\u002F.claude\u002Fcodememory-logs\u002Fsession-start.log` and `~\u002F.claude\u002Fcodememory-logs\u002Fdaemon.log`.\n- **Offline or CI hangs during compaction**: set `CODEMEMORY_COMPACTION_DISABLE_LLM=true`.\n- **Need to inspect runtime state**: use `\u002Fcodememory-status` and review `~\u002F.claude\u002Fcodememory.db`.\n\n## License\n\nMIT.\n","CodeMemory 是一个为 Claude Code 设计的持久化工程记忆层插件。它使用 SQLite 作为本地存储，保存会话中的决策、约束条件、失败记录以及压缩后的总结，并在长会话、复杂重构和多轮调试循环中重新引入这些上下文信息。其核心功能包括本地优先的记忆存储、提示时的相关信息检索、先前失败警告以及基于有向无环图的历史记录压缩等。CodeMemory 特别适用于需要长时间保持稳定需求和约束条件的编码场景、涉及设计理由保留的复杂代码重构过程，以及需要回顾以往错误尝试以避免重复问题的多轮调试情境。","2026-06-11 03:32:15","CREATED_QUERY"]