# Agent Notepad > Persistent, per-objective working memory for coding agents — one standalone git "notepad" repo per objective that survives context compaction, spans multiple code repos from a single session, keeps an append-only journal, and mirrors into an episodic memory index. Ships as a Claude Code plugin (hooks + skills + notepad template + a memory adapter). Evolves and supersedes handoff-auto. Use when setting up objective-scoped agent memory, running several long-lived concurrent agent sessions, surviving auto-compaction, enabling `/clear` instead of `/compact`, driving several code repos from one place without `cd`, or installing/uninstalling the notepad hooks. Triggers on "agent notepad", "working memory notepad", "per-objective memory", "scope-init", "survive compaction", "cross-repo agent memory", "supersede handoff-auto". - Skill: `onedro1d/agent-notepad` (Agent Skill, multi-file: 41 files) - Install (CLI): `npx skillmds@latest add onedro1d/agent-notepad` - Raw SKILL.md: https://api.skillmd.com/api/skills/onedro1d/agent-notepad/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: OneDro1d (https://skillmd.com/u/onedro1d) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/onedro1d/agent-notepad --- # agent-notepad — persistent, per-objective working memory ## What this is A **notepad** is one standalone git repo per objective (`-`, e.g. `proj-arbbot`), holding the agent's *working memory* for that objective. It survives context compaction, keeps history (append-only journal, not a rewrite), spans several code repos from a single session, and syncs across machines. It is the short-term, auto-loaded tier that complements a curated long-term store — and it **evolves and supersedes** handoff-auto: the same continuity machinery, now objective-scoped instead of cwd-scoped, with history and cross-repo reach. ⚠️ handoff-auto is deliberately UNBACKTICKED and unlinked here: it was REMOVED from this repo on 2026-09-04, and a backticked name reads to `tier-check.py` as a reference to a component this tier ships — which is what the gate caught. The plugin installer still UNWIRES its old hook entries from an existing `settings.json`; that is for machines installed before the removal, and it stays. Product = **a Claude Code plugin**: hooks + skills + a notepad template + a small Python memory adapter. No binary, no daemon. Full rationale in [`DESIGN.md`](./DESIGN.md). ## Why it beats naive auto-handoff handoff-auto keys by cwd → one rewritten file → parallel sessions clobber, no history, single-repo. A notepad gives **zero contention** (separate folder + cwd + git repo per objective), **append-only history**, and **cross-repo context** driven from one place via absolute paths (never `cd`). The episodic memory index is exercised at both ends by hooks (write-mirror on Stop, query on digest build), so "memory is actually used" is enforced, not left to agent discretion. ## The four layers | Layer | Anchored to | Where | |---|---|---| | **Working memory (Notes)** | the *task* | the notepad repo (`NOTES.md` + journal) — this skill | | **Per-repo context store** | *code* (`file:line`) | `/.claude/context/` — df-context-store | | **Episodic index** | journals, by prefix | the memory index (MemPalace ref impl) — mirror + digest | | **Curated** | distilled cross-project | the long-term store ([Engram](../../starter-kit/instance/AUTHENTICATION.md#engram) ref) — existing | ## Notepad layout ``` proj-arbbot/ CLAUDE.md # orientation: objective, repos-in-scope, read-first/dispatch rules NOTES.md # compact working memory, auto-loaded (≤150 lines, redacted) SCOPE.md # charter: objective, done-criteria, repo subset DIGEST.md # standing caveats, hand-maintained, COMMITTED, auto-loaded repos.manifest.json # the CODE repos this notepad drives sessions/ index.json # session metadata index _.jsonl # append-only journal, one file per session handoffs/ # deliberate structured handoff docs (/handoff → forces push) .claude/settings.json # notepad-scoped hooks incl. the commit gate ``` ## The hooks (what runs when) - **SessionStart** — best-effort `git pull`, then FILE-READS-ONLY inject `NOTES.md` + `DIGEST.md` + `repos.manifest.json` (~1–3 s). Outside a notepad, degrades to handoff-auto behavior. **The payload has no size ceiling, and this is load-bearing.** It is piped to `jq -Rs`, never passed as an argv element. Until 2026-09-04 it used `jq -n --arg`, and Linux caps one argv element at 128 KB (`MAX_ARG_STRLEN`) while macOS caps only the ~1 MB total — so a 259 KB `NOTES.md` restored fine on the maintainer's laptop and **injected zero bytes on every Linux box in the fleet**, with the hook still exiting 0. ⚠️ **A restore that emits nothing is indistinguishable from a notepad with nothing to say.** That is why the encode failure path now injects a WARNING naming `NOTES.md` and `DIGEST.md` instead of staying silent: the hook contract is *exit 0 always*, so the payload is the only channel that reaches the session — stderr is read by nobody. ⚠️ **Do not "fix" a large `NOTES.md` by capping the payload here.** Bloat is a real and separate problem; capping would restore the silent-truncation failure this removed. - **Stop** — append deterministic journal entries (files touched, commands, a stop marker), upsert `sessions/index.json`, **mirror the journal into the memory index**, best-effort `git push`. - **UserPromptSubmit** — soft nudge to keep `NOTES.md` current (backed by the PreCompact floor). - **PreCompact** — deterministic floor: snapshot recent intent into `NOTES.md` + journal before compaction, so `/clear` rehydrates losslessly. - **PreToolUse(Bash)** — the **commit gate** (ships in the *notepad's* `.claude/settings.json`, arms only in notepad sessions): blocks *agent* `git -C commit`s that drift from that repo's df-context-store. ## Install ```bash # from the plugin dir; installs to the STABLE path ~/.claude/hooks/agent-notepad/, # merges the four user-level Notes hooks into ~/.claude/settings.json (idempotent), # installs this skill, and UNWIRES handoff-auto (files kept — reversible). plugin/install.sh # targets $HOME plugin/install.sh --target DIR # targets DIR (used by the test harness against a temp HOME) ``` The installer backs up `settings.json` before editing it. To reverse: restore the backup and re-wire handoff-auto. As a Claude Code plugin, the four Notes hooks are declared in `plugin/.claude-plugin/plugin.json` via `${CLAUDE_PLUGIN_ROOT}`. ## A day in the life 1. `/scope-init proj-arbbot` — creates the notepad repo, interviews for objective + in-scope code repos, warm-starts `NOTES.md`, derives the memory wing (`proj`). 2. SessionStart auto-loads `NOTES.md` + `DIGEST.md`; you resume from state instead of re-deriving it. You work across the manifest's repos via absolute paths. 3. As you go, `NOTES.md` stays fresh (nudged each turn); durable code-anchored learnings go to each repo's `FINDINGS.md`/`DECISIONS.md` (df-context-store), not here. 4. You `git -C /abs/code-repo commit` — the commit gate checks it against that repo's store; a drifting commit is blocked with a fix hint, a compliant one passes. 5. On Stop, the journal appends + mirrors into the memory index; a background digest build queries the `proj` wing so a *sibling* objective's recent activity shows up in `DIGEST.md`. 6. Context fills → PreCompact writes the floor. You `/clear` instead of `/compact`; the next session rehydrates goal + next-action from `NOTES.md` alone. 7. At a real milestone, `/handoff` writes `handoffs/-.md` and forces a push. ## Routing (where does this note go?) Ephemeral task progress → `NOTES.md`. Durable + code-anchored + single-repo → that repo's `FINDINGS`/`DECISIONS`. Cross-scope episodic (same prefix) → the memory index (mirror + digest). Deliberate handoff → `handoffs/` + remote. Distilled/canonical → the curated store. ### Publishing a handoff commits the POINTER with the DOCUMENT `lib/publish-handoff.sh` stages `NOTES.md` and `DIGEST.md` alongside the handoff file, so the refreshed Notes land in the same commit. This is not tidiness. SessionStart injects `NOTES.md` and only a **pointer** to the newest handoff — so a cold reader told the Notes are current has no reason to open the handoff at all. Committing the document without the pointer keeps the artifact and loses the only route to it, which is exactly what this tier exists to prevent. Measured twice on 2026-09-04, on two machines, as ` M NOTES.md` left in the working tree after the publisher had exited 0. ⚠️ **It stages those two files and nothing else — deliberately not `add -A`.** A notepad also holds a manifest, a charter and session journals that other machinery writes on its own schedule; sweeping them in publishes a half-written record from a different tier under this one's commit message. ⚠️ **The commit is not best-effort; only the push is.** A flaky remote must not block a local checkpoint, but a *rejected commit* reported as success loses the checkpoint entirely — so a non-zero commit (other than "nothing to commit") is surfaced and returns non-zero. ## Relationship to handoff-auto Evolution, not coexistence: the handoff-auto machinery becomes the **Notes** tier; its hooks are extended and the commit gate is added. The installer unwires handoff-auto (leaving its files in place, reversible). Outside a notepad, behavior degrades to today's. ## Non-goals (v1) No new DB/service (files are truth) · no live context-% trigger · no automatic `/clear` (habit) · no shared mutable files · no cross-*group* auto-sharing · manual human code-commits are not governed (agent commits only).