Git Layered Memory — AI skill for Claude Code

git-layered-memory

给 AI coding agent 的工作区一套**跨会话、跨 AI、可检索**的长期记忆。 纯 markdown + git，**零依赖、零数据库、不调用任何 LLM**。

**要解决的问题**：agent 的长期记忆有两个同时成立的约束 —— **要全**（决策与踩坑不能丢，内容只会增长）与 **要省**（每次会话都得注入，token 是硬预算）。天真做法是把一切塞进一个 `MEMORY.md` 整体注入，结果是预算被撑爆、模型读到被截断的记忆，而最有价值的老决策正好在被截断的那一半。

**本项目的解法**：按「**是否进注入**」把记忆切成四层。注入层只留索引与稳定事实，全文沉到检索层，用 `git grep` 按需捞。实测一条 2,897 字符的决策写成规范块形态，**只花 +23 码点注入预算**。

① AGENTS.md          宪法  ─┐
② MEMORY.md          核心  ─┴─ 每次会话注入（≤15000 码点预算）
③ memory/decisions.md 决策 ─┐
④ memory/sessions/*.md 会话 ─┴─ 不注入，git grep / blame 按需检索

---

快速开始

需要 **Node.js ≥ 18**（零依赖 ESM，不装任何包）。

git clone https://github.com/Singingmen/git-layered-memory.git
SKILL="$(pwd)/git-layered-memory"

# 新工作区：铺好四层骨架 + 向 AGENTS.md 注入协议块
node "$SKILL/scripts/memory-init.mjs" --root /path/to/your/workspace --harness dsh --apply

# 闸门：注入层体积、ADR 索引一致性、编号唯一、引用可解析
node "$SKILL/scripts/memory-lint.mjs" --root /path/to/your/workspace

已有单体 `MEMORY.md` 需要拆分，先看迁移计划（默认 dry-run，不写盘）再落盘：

node "$SKILL/scripts/memory-split.mjs" --root . --harness dsh --sections 1,4,6,7 --prune-header
node "$SKILL/scripts/memory-split.mjs" --root . --harness dsh --sections 1,4,6,7 --prune-header --apply
node "$SKILL/scripts/memory-lint.mjs" --root .

⚠️ `--root` **必填**（四个脚本一致）；缺省 **exit 2**，**绝不回退到当前目录**。`--sections` 的节号**随你的 `MEMORY.md` 布局而变** —— 首次务必先看 dry-run 计划再 `--apply`。

跑测试：

node tests/run.mjs            # 全部套件
node tests/run.mjs 02 03      # 只跑文件名含 02 / 03 的
node tests/run.mjs --json     # 机器可读摘要

---

仓库结构

git-layered-memory/
├── SKILL.md                 技能入口（使用者向）
├── README.md                本文：首页 + 维护者向设计说明
├── spec.md                  接口契约 v1
├── LICENSE                  MIT
├── scripts/
│   ├── memory-init.mjs        初始化新工作区
│   ├── memory-lint.mjs        体积与一致性闸门（唯一该进 CI 的脚本）
│   ├── memory-split.mjs       单体记忆迁移（默认 dry-run）
│   ├── memory-find.mjs        检索助手（git grep / blame 封装）
│   └── _lib.mjs               共享内部模块（不是 CLI）
├── templates/