{"id":50804633,"url":"https://github.com/zhjai/agent-lessonbook","last_synced_at":"2026-06-12T23:36:00.828Z","repository":{"id":361917234,"uuid":"1256385211","full_name":"zhjai/agent-lessonbook","owner":"zhjai","description":"Governance-layer memory for AI agents — permission-separated control/state/lessons so an agent carries rules and lessons across tasks without rewriting its own authority. A trust boundary, not retrieval (unlike Mem0/Zep). Standalone-usable.","archived":false,"fork":false,"pushed_at":"2026-06-03T09:48:05.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T23:35:59.757Z","etag":null,"topics":["agent-memory","agent-skill","ai-agents","ai-coding-agents","ai-governance","ai-guardrails","ai-safety","claude-code","claude-code-skill","guardrails","llm","policy-engine"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhjai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T18:19:13.000Z","updated_at":"2026-06-03T09:48:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zhjai/agent-lessonbook","commit_stats":null,"previous_names":["zhjai/agent-memory","zhjai/agent-lessonbook"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zhjai/agent-lessonbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhjai%2Fagent-lessonbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhjai%2Fagent-lessonbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhjai%2Fagent-lessonbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhjai%2Fagent-lessonbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhjai","download_url":"https://codeload.github.com/zhjai/agent-lessonbook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhjai%2Fagent-lessonbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34266915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-skill","ai-agents","ai-coding-agents","ai-governance","ai-guardrails","ai-safety","claude-code","claude-code-skill","guardrails","llm","policy-engine"],"created_at":"2026-06-12T23:36:00.157Z","updated_at":"2026-06-12T23:36:00.811Z","avatar_url":"https://github.com/zhjai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-lessonbook\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.svg\" alt=\"agent-lessonbook — reviewed memory for AI coding agents: capture corrections and drift lessons, but the worker can't promote its own notes to authority\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e · \u003ca href=\"README.zh.md\"\u003e中文\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"version\" src=\"https://img.shields.io/badge/version-0.3.1-informational\"\u003e\n  \u003cimg alt=\"works with\" src=\"https://img.shields.io/badge/Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20any%20agent-444\"\u003e\n  \u003cimg alt=\"no backend\" src=\"https://img.shields.io/badge/no%20vector%2Fgraph-files%20only-2ea043\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-yellow\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **Reviewed memory for AI coding agents.** Capture user corrections, task constraints, and drift lessons during a long task — without letting the worker promote its own notes into project authority.\n\u003e\n\u003e *Reviewed corrections, constraints, and lessons the project carries forward — not tutorials, not a chat log.*\n\nAI coding agents already have memory. The failure this targets is narrower: **mid-task, you correct the agent or clarify a requirement — and that lesson either evaporates, or silently becomes future \"authority\" with no review.**\n\n- You clarify *\"actually, chart titles must include the run name\"* — the agent does it once, then forgets next session.\n- The agent drifts, fixes the immediate bug, but never records *why* it drifted — so the next run repeats it.\n- Or worse: the agent quietly rewrites a stable rule it found inconvenient, and nothing stopped it.\n\n`agent-lessonbook` is a **project-local review queue** for those moments. The worker can record clarified constraints, corrections, and drift notes, and can *propose* lessons. It **cannot approve its own notes or rewrite project authority** — promotion is a human review step. Plain files that diff and review like code. No vector store, no graph DB, no backend.\n\n\u003e `agent-lessonbook` does not make agents reliably notice their own drift; it captures drift when a user, a verifier, a failing check, or a concrete self-observed error exposes it.\n\n## Where this fits\n\nYou don't replace your existing memory — you add a review boundary on top of it.\n\n- **Built-in agent memory** (Claude Code, Codex, Copilot): good for recall, preferences, project context.\n- **Memory engines** (Mem0, Zep, Letta, LangMem): good for retrieval, graph memory, personalization, scale.\n- **agent-lessonbook**: decides *which* recorded corrections and lessons are allowed to influence future behavior — review before authority.\n\n\u003e Most memory tools answer *\"how do we store and retrieve context?\"*. `agent-lessonbook` answers *\"which memories are allowed to influence future agent behavior?\"*\n\n### vs your agent's built-in memory\n\nClaude Code (auto memory, on by default) and Codex (memories) **already auto-record engineering details** — build commands, architecture notes, style. `agent-lessonbook` doesn't compete with that, and on pure recall it's weaker (capture is a skill the agent invokes, not background summarization). What it adds is what both vendors deliberately leave out: **their own docs say auto memory is a *recall layer*, not authority** — \"rules that must always apply\" belong in CLAUDE.md / AGENTS.md, maintained by a human. `agent-lessonbook` is the structured, git-reviewed workflow for exactly that promotion.\n\n\u003e Built-in auto memory helps an agent remember what it *thinks* it learned. `agent-lessonbook` is the git-reviewed gate that decides which lessons become **project authority — for every agent on the repo.**\n\n## What it captures (and what it doesn't)\n\nIt records only **evidence-backed** things that should carry forward *and* that the worker shouldn't get to canonize on its own — five types:\n\n1. **User corrections / acceptance prefs** — \"actually, chart titles must include the run name\".\n2. **Drift root-causes** — *why* a wrong turn happened, so the next run avoids it.\n3. **Negative constraints** — a \"never do X again\" learned from a mistake.\n4. **Repo pitfalls proven by failure** — \"running test A without env B gives false confidence\".\n5. **Authority-relevant architecture constraints** — \"approved lessons live in `control/`; workers can't write there\".\n\nIt deliberately does **not** own: how to run tests / validate the repo (→ README, Makefile, CI), project conventions and env setup (→ `CLAUDE.md` / `AGENTS.md` / lockfiles), task status and open questions (→ `run_state.yaml`, no review needed), or your personal output style (→ built-in agent memory). Keeping the journal to high-signal, review-worthy evidence is the point — a noisy \"record everything\" log defeats it.\n\n## The permission model (who can write what)\n\n```\n🔒 control/   read-only to the worker (human / CI maintains)\n   rules.md                 stable rules the agent must obey, cannot edit\n   approved_lessons/        reviewed, promoted lessons\n     index.yaml             summary-first index\n\n✍️ state/     worker-writable, NOT a source of truth\n   tasks/\u003ctask_id\u003e/\n     run_state.yaml         task checkpoint + active constraints (belief, not truth)\n     correction_journal.md  clarified requirements + drift notes, as they happen\n     candidate_lessons.md   proposed lessons, PENDING human review (no self-approve)\n```\n\n**Invariants:**\n- The worker **cannot write `control/`** — mount it `read_only` (Claude Code subagent memory / Managed Agents memory stores enforce read_only vs read_write at the filesystem level; use that, don't build your own).\n- `state/` is **working memory, not truth** (`run_state` = \"what the agent believes it did\").\n- New lessons go to `candidate_lessons.md`; **promotion to `approved_lessons/` is a reviewed action — the worker proposes, never self-approves.** Promotion is a human git action, not something the worker can trigger.\n\n## Skills (process, not authority)\n\nThree skills, all worker-side process — none of them can grant authority:\n\n- [`resume-context`](skills/resume-context/SKILL.md) — at start/resume, read `control/` rules + approved lessons + task state, and surface the **active constraints** for this run.\n- [`correction-capture`](skills/correction-capture/SKILL.md) — when the user corrects/clarifies mid-task, *or* drift is exposed (by the user, a check, or a concrete self-observed error), record it to `state/.../correction_journal.md`: what was expected, what happened, likely cause, prevention.\n- [`lesson-propose`](skills/lesson-propose/SKILL.md) — at wrap-up, turn the journal into *candidate* lessons for review, classified by target tier. **Proposes only; never promotes.**\n\nPromotion (candidate → `approved_lessons/` or `rules.md`) is deliberately **not a skill** — it's a human review step in git, so the worker can never reach authority through tool use.\n\nCapture is a skill the agent *invokes*, so it can be missed. To fire it reliably, add the host-agnostic nudge (one line in `CLAUDE.md` / `AGENTS.md`) or optional Claude Code / Codex hooks — they only *trigger* capture, never write or promote. See [`integrations/`](integrations/).\n\n## Quick start\n\n```bash\nnpx skills add zhjai/agent-lessonbook -g -a claude-code   # or -a codex, cursor, … any host\n```\n\nA normal loop on a long task:\n\n1. **Start:** `resume-context` loads the rules + approved lessons + last task state, and lists the active constraints.\n2. **Mid-task:** you say *\"actually, the export must include the month column\"* → `correction-capture` writes it to the journal and adds it to the run's active constraints, so it isn't forgotten three steps later.\n3. **Drift exposed:** a check fails / you point out a miss → `correction-capture` records the cause + how to prevent it next time.\n4. **Wrap-up:** `lesson-propose` files the keepers into `candidate_lessons.md`.\n5. **You review** the candidates and promote the good ones into `control/` (a normal git commit). Only then are they authority.\n\nIt's just files — `git diff` your `state/` and `control/` like any other change. No backend to run.\n\n## Pairs with agent-completion-gate\n\n`agent-lessonbook` captures **process lessons during** the work. [`agent-completion-gate`](https://github.com/zhjai/agent-completion-gate) is a separate, standalone tool for **acceptance at the end** (the agent can't self-declare a task complete). They are **independent** — the gate never reads this lessonbook at runtime. The only link is human-mediated: a recurring lesson you review here may prompt *you* to add a check to the gate's protected manifest.\n\n## Status\n\n`v0.3.1` preview. MIT. Portable, agent-agnostic, file-based, standalone. (Renamed from `agent-memory`.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhjai%2Fagent-lessonbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhjai%2Fagent-lessonbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhjai%2Fagent-lessonbook/lists"}