@dosx/agent-memory 0.0.13

package/skills/agent-memory/references/install-hooks.md

@@ -0,0 +1,113 @@
+# `/agent-memory install hooks`
+
+Print how to install or refresh lifecycle hooks for one harness. **This skill
+does not copy scripts, merge configs, or run installers** — the user must run
+the shell script or `npx` CLI themselves (trust boundary for security audits).
+
+Does **not** create `.agents/memory/`, touch project memory content, or wire
+agent instruction files — use `init` for that.
+
+Also used by `init` (step 6) and `update` (refresh already-installed harnesses)
+to print the same instructions.
+
+## Invocation
+
+```text
+/agent-memory install hooks <harness>
+/agent-memory install hook <harness>    # alias (singular)
+```
+
+Accepted `<harness>` values (aliases in parentheses):
+
+| Harness    | Aliases       | Dir (created by installer if missing) | Installer writes into                    |
+| ---------- | ------------- | ------------------------------------- | ---------------------------------------- |
+| `cursor`   | —             | `.cursor/`                            | `.cursor/hooks/` + merge `hooks.json`    |
+| `claude`   | `claude-code` | `.claude/`                            | `.claude/hooks/` + merge `settings.json` |
+| `codex`    | —             | `.codex/`                             | `.codex/hooks/` + merge `hooks.json`     |
+| `opencode` | —             | `.opencode/`                          | `.opencode/hooks/` + plugin `.ts`        |
+| `copilot`  | `github`      | `.github/`                            | `.github/hooks/` + `agent-memory.json`   |
+| `gemini`   | —             | `.gemini/`                            | `.gemini/hooks/` + merge `settings.json` |
+
+Canonical hook sources live under `hooks/` in the
+[agent-memory](https://github.com/diegoos/agent-memory) repository (tag matching
+this skill's `metadata.version`).
+
+## Steps
+
+1. **Guard.** If `.agents/memory/` does not exist, stop and suggest
+   `/agent-memory init` first. (Skip this guard when called from `init` step 6.)
+
+2. **Parse harness.** Read `<harness>` from the invocation. Normalize aliases
+   (`claude-code` → `claude`, `github` → `copilot`). If missing, stop and list
+   accepted values.
+
+3. **Prerequisite dir.** The user-run installer (`install-hooks.sh` / `npx`)
+   **creates** the harness prerequisite directory if missing (e.g. `.cursor/`,
+   `.opencode/`). The skill itself still must **not** create those dirs — only
+   print the install commands.
+
+4. **Print install instructions (do not execute).** Read this skill's
+   `metadata.version` (e.g. `0.0.13`). Tell the user to review and run **one** of
+   the following from the **project root** (never embed
+   `raw.githubusercontent.com` URLs):
+
+   **Preferred — npx:**
+
+   ```bash
+   npx @dosx/agent-memory install hooks <harness>
+   ```
+
+   **Pinned tag (optional):**
+
+   ```bash
+   npx --yes github:diegoos/agent-memory#0.0.13 -- install hooks <harness>
+   ```
+
+   (Replace `0.0.13` with this skill's `metadata.version` when it differs.)
+
+   **Alternative — shell script:** open the GitHub release page for the matching
+   tag (Releases → `0.0.13`, or the tag tree on GitHub), review
+   `hooks/install-hooks.sh`, then from a checkout of that
+   tag:
+
+   ```bash
+   bash hooks/install-hooks.sh <harness>
+   ```
+
+   Replace `<harness>` with the normalized harness name. Remind: the installer
+   needs Node.js for JSON merges; it creates the harness directory if missing;
+   Codex users should run `/hooks` in the TUI after install; Cursor may need a
+   hooks reload.
+
+5. **Report.** List: harness, that hooks were **not** written by the agent, and
+   the exact commands printed. Suggest `/agent-memory sync` at the next
+   checkpoint after the user installs.
+
+## Detecting installed harnesses (`update`)
+
+A harness counts as **already installed** when its prerequisite dir exists
+**and** any of these markers is present:
+
+| Harness    | Marker (any one)                                                                        |
+| ---------- | --------------------------------------------------------------------------------------- |
+| `cursor`   | `.cursor/hooks/agent-memory-sync.sh` or agent-memory in `.cursor/hooks.json`            |
+| `claude`   | `.claude/hooks/agent-memory-sync.sh`                                                    |
+| `codex`    | `.codex/hooks/agent-memory-sync.sh`                                                     |
+| `opencode` | `.opencode/plugin/agent-memory.ts` or `.opencode/hooks/agent-memory-sync.sh`            |
+| `copilot`  | `.github/hooks/agent-memory.json` or `.github/hooks/agent-memory-sync.sh`               |
+| `gemini`   | `.gemini/settings.json` containing agent-memory or `.gemini/hooks/agent-memory-sync.sh` |
+
+For `update`, for **each** installed harness print the refresh commands from
+step 4 (no agent copy/merge). Skip harnesses with no marker even if the
+prerequisite dir exists.
+
+## Behavior
+
+Hooks run a **deterministic checkpoint** — `active-work/` (Touched files, Task
+stub), `log.md` (session heading on session start + file-path bullets), and
+`current.md` _In progress_ on session start. Semantic log text and
+`decisions.md` stay agent-owned. See the
+[hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).
+
+Optional git `pre-commit` is **not** installed by this command — see the same
+[hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).

package/skills/agent-memory/references/lint.md

@@ -0,0 +1,113 @@
+# `/agent-memory lint`
+
+Check `.agents/memory/` for structural and consistency problems. Report
+findings; fix only what is safe, and never change user content without
+confirmation.
+
+## Steps
+
+1. **Guard.** If `.agents/memory/` does not exist, suggest `/agent-memory init`.
+
+2. **Structural checks (deterministic).** Run from `.agents/memory/`:
+
+   ```bash
+   # Broken cross-references: relative links pointing to files that no longer exist
+   grep -rhoE '\]\(\./[^)]+\)' . | sed -E 's/^\]\(\.\/([^)]+)\)$/\1/' \
+     | sort -u | while read -r f; do test -e "$f" || echo "missing: $f"; done
+
+   # Orphaned files: domains/features not referenced from index.md
+   find domains features -name '*.md' 2>/dev/null | while read -r f; do
+     grep -q "$(basename "$f")" index.md || echo "orphan: $f"
+   done
+
+   # Stale per-branch active-work: a file whose branch no longer exists
+   # (skipped when git lists no branches — no commits yet / not a git repo)
+   branches=$(git branch --format='%(refname:short)' | sed 's#[^A-Za-z0-9._-]#-#g')
+   [ -n "$branches" ] && find active-work -name '*.md' ! -name 'TEMPLATE.md' 2>/dev/null | while read -r f; do
+     printf '%s\n' "$branches" | grep -qx "$(basename "$f" .md)" || echo "stale: $f"
+   done
+   ```
+
+   Also report if `.agents/memory/.version` is missing — the memory was likely
+   installed manually without the skill, so `update` cannot track its version.
+
+   **Instruction wiring checks** — run from the **project root** (not from
+   `.agents/memory/`). Detect agent-memory blocks via `<!-- <agent-memory> -->`
+   … `<!-- </agent-memory> -->` or legacy plain tags.
+
+   ```bash
+   # Helper: true if file contains an agent-memory block
+   has_block() { grep -q '<agent-memory>' "$1" 2>/dev/null; }
+
+   # (a) Potential double-injection — block in AGENTS.md AND a harness-native file
+   # when AGENTS.md is not needed as a shared carrier
+   agents_block=false; has_block AGENTS.md && agents_block=true
+   codex_or_opencode=false
+   { test -d .codex || test -d .opencode; } && codex_or_opencode=true
+   claude_delegates=false
+   test -f CLAUDE.md && grep -qE '@(\./)?AGENTS\.md' CLAUDE.md && claude_delegates=true
+   gemini_delegates=false
+   test -f GEMINI.md && grep -qE '@(\./)?AGENTS\.md' GEMINI.md && gemini_delegates=true
+   shared_carrier=false
+   { $codex_or_opencode || $claude_delegates || $gemini_delegates; } && shared_carrier=true
+
+   if $agents_block; then
+     has_block .cursor/rules/agent-memory.mdc && \
+       ! $shared_carrier && echo "double-injection: AGENTS.md + .cursor/rules/agent-memory.mdc"
+     has_block .github/instructions/agent-memory.instructions.md && \
+       ! $shared_carrier && echo "double-injection: AGENTS.md + agent-memory.instructions.md"
+   fi
+
+   # (b) Delegation canary — block in BOTH delegator and AGENTS.md
+   for f in CLAUDE.md GEMINI.md; do
+     test -f "$f" || continue
+     grep -qE '@(\./)?AGENTS\.md' "$f" || continue
+     has_block "$f" && has_block AGENTS.md && \
+       echo "delegation-canary: block in $f and AGENTS.md (remove from $f)"
+   done
+   ```
+
+   Report each finding as a **warning** with the suggested fix (remove redundant
+   block from the delegating file or from `AGENTS.md` when not a shared
+   carrier). `--fix` may offer to remove the block from the delegating file in
+   case (b) (**sensitive** — show diff, confirm per file). `--fix` never removes
+   blocks from `AGENTS.md` when it is a shared carrier for
+   codex/opencode/delegation.
+
+3. **Semantic checks (judgment — report as warnings to review).** These need
+   reading, not grepping; surface them for the user to confirm rather than
+   auto-fixing:
+   - **Stale `current.md`** — does it still match the actual codebase state?
+   - **Duplication** — the same fact recorded in more than one file.
+   - **Contradictions** — files (or a file and the code) that disagree.
+   - **Bloat** — always-loaded files (`current.md`, active-work) grown long, or
+     verbose entries that waste tokens; suggest trimming.
+
+4. **Report.** Group findings as **errors** (broken links, orphans, stale
+   per-branch files) and **warnings** (semantic). For each, name the file and
+   the problem.
+
+5. **Fix offer.** Offer to fix only safe issues (e.g. remove a dead link, add an
+   orphan to `index.md`). Any fix that edits user content (`current.md`,
+   `decisions.md`, `domains/*`, …) must be confirmed first — show the diff. For
+   stale `current.md` / active-work / `log.md`, suggest `/agent-memory sync`
+   rather than editing by hand.
+
+   `--fix` — with this flag, also offer to **delete stale per-branch
+   `active-work/<branch>.md` files** (files whose branch no longer exists) and,
+   for **delegation-canary** findings (step 2), offer to remove the redundant
+   block from `CLAUDE.md`/`GEMINI.md` that delegate via `@AGENTS.md` (each
+   removal sensitive — show diff, confirm). Each deletion is still confirmed one
+   by one (it removes a file, so it is sensitive) unless combined with an
+   explicit "delete all stale" approval. `--fix` never deletes anything other
+   than stale `active-work` files, never touches `TEMPLATE.md`.
+   Delegation-canary block removal edits only the agent-memory delimiters in
+   `CLAUDE.md`/`GEMINI.md` (with confirmation). For other user content, fallback
+   to `sync` or a manual edit.
+
+## Notes
+
+- This mirrors the "Memory lint" section of `instructions.md`; keep them
+  aligned.
+- No `markdownlint` here — Markdown style is the concern of the source repo, not
+  of the installed memory in a user's project.

package/skills/agent-memory/references/sync.md

@@ -0,0 +1,120 @@
+# `/agent-memory sync`
+
+Refresh the four files that rot between commands — `current.md`, your branch's
+`active-work/<branch>.md`, `log.md`, and `index.md` — from **actual repo state**
+(`git`) and session context, not chat history. This is the executable form of
+the _During_ / _After_ / _Flush early_ workflow in `instructions.md`.
+
+Use it at any checkpoint: end of a task, before a commit, before context
+compaction, or when picking work back up. Safe and idempotent.
+
+## Flags
+
+- `--auto` — apply all proposed diffs without the per-file `AskQuestion` prompt.
+  Use at routine checkpoints (where you would approve everything anyway) to keep
+  the flush low-friction; without it, sync is the careful, per-file-confirm form
+  suited to the first run or a manual review. `--auto` still shows the diffs in
+  the report after applying, and still skips fields for which it has no evidence
+  (it never invents progress or log bullets).
+- `--force` — reserved for explicit user override; does not skip the vision
+  uncertainty gate below.
+
+## Boundary
+
+Sync writes only to: `current.md`, `active-work/<branch>.md`, `log.md`, and
+`index.md` (domains/features links and lazy-file links when evidence exists). It
+**never** touches `decisions.md`, `instructions.md`, `domains/*` / `features/*`
+body content, or any file outside `.agents/memory/`. It never deletes anything
+except replacing placeholder lines inside the four target files.
+
+Hooks maintain `log.md` session headings and file-path bullets from `git`; sync
+adds semantic bullets, refines summaries/types, and aligns `decisions.md`
+indirectly (sync still does not write `decisions.md` — the agent must). The
+split is the same on every harness — see `instructions.md` → _Harness parity —
+memory contract_.
+
+## Steps
+
+1. **Guard.** If `.agents/memory/` does not exist, stop and suggest
+   `/agent-memory init`.
+
+2. **Resolve the branch.** Run `git branch --show-current` (fall back to `local`
+   if HEAD is detached or not a git repo). Sanitize every character outside
+   `[A-Za-z0-9._-]` to `-`. This is the active-work filename.
+
+3. **Ensure the active-work file.** If `active-work/<branch>.md` is missing,
+   create it from `active-work/TEMPLATE.md` and set its `Branch:` header to the
+   real branch name (never reverse the lossy filename). If it exists, leave the
+   header as-is.
+
+4. **Gather evidence (read-only, from `git` and memory).**
+
+   ```bash
+   git log --since="<last-log-date>" --pretty='%h %ad %s' --date=short --no-merges
+   git diff --stat <base>..HEAD          # base: main/master or origin/<branch>@{u}
+   git status --porcelain
+   git diff --name-only <last-log-sha>..HEAD 2>/dev/null || true
+   ```
+
+   Session ID: `AGENT_MEMORY_SESSION_ID`, harness stdin (`session_id` /
+   `conversation_id` / `sessionId`), or `current_session_id` from
+   `.agents/memory/.hook-sync-state`.
+
+   For `log.md`, find the **current session** heading:
+   `## [YYYY-MM-DD] [session-id] ...` (session-id bracket optional). Append
+   bullets under it; open a new heading only for a new session.
+
+   `<last-log-date>` comes from the newest `## [YYYY-MM-DD]` in `log.md`. If
+   empty, use the repo's first commit or `HEAD~20` as a sane default.
+
+   `<last-log-sha>` is `last_processed_head` from
+   `.agents/memory/.hook-sync-state` (written by hooks after each checkpoint).
+   If empty, skip the `git diff --name-only <last-log-sha>..HEAD` line — there
+   is no prior processed commit to diff from.
+
+5. **Vision gate (unless `--auto`).** If `vision.md` does not exist or looks
+   stale/ambiguous and docs do not clarify product purpose, **ask the user**
+   before creating or rewriting `vision.md`. If you inferred a vision change
+   during sync, note it in the report for the user to confirm at session end.
+
+6. **Propose updates (one diff per file).** Show each as a unified diff. Unless
+   `--auto` is set, confirm via `AskQuestion` before writing — sync touches
+   project memory, so the "confirm before editing user content" rule applies.
+   Allow approve / skip per file. Under `--auto`, apply all proposed diffs
+   without prompting and report them after.
+   - **`active-work/<branch>.md`** — fill/refresh _Task_ (infer from branch
+     name, user context, `current.md`, recent `log.md`), _Progress_, _Touched
+     files_ (from `git diff --name-only`), and _Blockers_. Keep _Notes_ as-is
+     unless evidence supports an update. Overwrite only fields the evidence
+     supports.
+   - **`log.md`** — maintain **one heading per session**:
+     `## [YYYY-MM-DD] [session-id] [type] short summary` with `-` bullets for
+     concrete changes this session. Hooks may have appended ``- `path` ``
+     bullets already — add semantic bullets; refine type/summary; dedupe. Oldest
+     first / newest at bottom.
+   - **`current.md`** — refresh _Version / milestone_, _Done_, _In progress_
+     (list each open `active-work/*.md` with a one-line branch goal), from
+     evidence plus active-work files. Move completed branch work to _Done_ when
+     the active-work file is gone. _Next steps_ **only** if an explicit
+     roadmap/plan exists — remove or leave placeholder otherwise; never infer.
+   - **`index.md`** — for every existing lazy file (`vision.md`,
+     `architecture.md`, `patterns.md`, etc.) and every `domains/*.md` /
+     `features/*.md` not yet listed, add a link (replace `_None yet._` the first
+     time). Remove links to deleted files. Do not remove valid entries.
+
+7. **Apply approved diffs** only, with `Edit`/`Write` scoped to
+   `.agents/memory/**`. Skip anything the user declined.
+
+8. **Report.** List each file: updated, skipped, or unchanged — and one line on
+   what the next agent should read to continue (the branch's active-work file
+   plus `current.md`). If `vision.md` may need user input, say so explicitly.
+
+## Notes
+
+- Sync is **additive and conservative** for `current.md` facts — flag staleness
+  for `lint` instead of silent deletion.
+- If `git` is unavailable, fall back to reading recently modified files under
+  the project and ask the user to confirm what changed.
+- Remind the agent to update `decisions.md`, `architecture.md`, and
+  `patterns.md` when their triggers fired — sync does not write those files.
+- Mirrors the _Flush early_ section of `instructions.md`; keep them aligned.

package/skills/agent-memory/references/update.md

@@ -0,0 +1,145 @@
+# `/agent-memory update`
+
+Migrate an existing `.agents/memory/` to the latest structure from this skill's
+`vendor/` — **without ever altering the project's memory content.** It also
+refreshes the memory **block** inside harness instruction files, **only**
+between the `<!-- <agent-memory> -->` … `<!-- </agent-memory> -->` delimiters
+(or legacy plain `<agent-memory>` … `</agent-memory>` tags, which `update`
+migrates to the comment form). Hook refresh is **instructions only** (user-run
+installer).
+
+## Boundary (read before doing anything)
+
+- **Project memory (NEVER touch):** `current.md`, `active-work/*`,
+  `decisions.md`, `log.md`, `domains/*`, `features/*`, and any user-authored
+  content.
+- **Scaffolding (may change, see rules):** `instructions.md`, the structural
+  sections of `index.md`, the `.version` file, brand-new core files, and the
+  agent-memory block in harness instruction files.
+- **Outside the block (NEVER touch):** any content in instruction files outside
+  the agent-memory delimiters (`<!-- <agent-memory> -->` …
+  `<!-- </agent-memory> -->`, or legacy plain tags). For
+  `.cursor/rules/agent-memory.mdc`, preserve YAML frontmatter — refresh only the
+  delimited body.
+
+## Canonical memory block
+
+The exact block `init` writes and `update` refreshes is defined in
+[`references/agent-block.md`](./agent-block.md) — read it from there; do not
+inline the block text here. Each wired file's block is **replaced verbatim**
+with that canonical block during update (single source of truth).
+
+**Instruction file targets** (same as `init`; see `references/init.md` for
+carrier rules):
+
+| File                                                | Notes                                                   |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`               | Root agent files                                        |
+| `.cursor/rules/agent-memory.mdc`                    | Compare body only; keep `alwaysApply: true` frontmatter |
+| `.github/instructions/agent-memory.instructions.md` | Copilot path-specific; keep `applyTo: "**"` frontmatter |
+
+## Steps
+
+1. **Guard.** If `.agents/memory/` does not exist, stop and suggest
+   `/agent-memory init`.
+
+2. **Read versions.** Installed = `.agents/memory/.version`. Latest = the newest
+   version section in this skill's `vendor/UPDATE.md`. If equal, still run step 5
+   (refresh instruction blocks) before reporting "already up to date".
+
+3. **Select migrations.** Read this skill's `vendor/UPDATE.md` (see `SKILL.md` →
+   Repository source) and collect every entry with a version greater than the
+   installed version, up to the latest. Each change is tagged `safe` or
+   `sensitive`. **Skip** any item marked **superseded** (e.g. a later version
+   says it supersedes an earlier sensitive step) — do not apply superseded
+   migrations.
+
+4. **Apply, conservatively:**
+   - **Automatic (no prompt):**
+     - Create new core files that are missing.
+   - **Always confirm with a diff before applying:**
+     - `instructions.md` when the installed copy differs from the skill's
+       current `vendor/memory/instructions.md` (identical → nothing to do).
+     - Any change to a file that can hold user content — including `index.md`
+       (merge structural sections, **preserve the user's Domains/Features
+       lists**).
+     - Any rename, move, or deletion.
+   - **Skip superseded items** — e.g. do **not** agent-merge `.cursor/hooks.json`
+     for `afterFileEdit` when `UPDATE.md` marks that 0.0.10 sensitive step as
+     superseded (hooks refresh is user-run installer only).
+   - Present each sensitive change as a unified diff and ask the user to
+     approve, skip, or abort. Apply only what is approved.
+
+5. **Refresh instruction blocks.** Read the canonical block from
+   [`references/agent-block.md`](./agent-block.md). For **each wired target**
+   that exists at the project root (table above), decide what changed:
+   - **A delimited block exists** (`<!-- <agent-memory> -->` …
+     `<!-- </agent-memory> -->`, or legacy plain `<agent-memory>` …
+     `</agent-memory>`): compare its current text (between the delimiters,
+     inclusive) against the canonical block, byte-for-byte. **Identical → skip
+     (already current).** Different → replace block content with the canonical
+     block (comment delimiters). For `.mdc`, replace only the delimited body;
+     preserve existing frontmatter (or apply the canonical frontmatter from
+     `agent-block.md` — `alwaysApply: true` for Cursor, `applyTo: "**"` for
+     Copilot — if missing). **Sensitive** — show the unified diff, confirm
+     first. Never touch anything outside the delimiters.
+   - **No block yet, but a legacy `## Agent Memory` section exists** (installed
+     by an older `init` without delimiters): replace that section with the
+     canonical block (delimiters and content). **Sensitive** — show the diff,
+     confirm first.
+   - **No block and no legacy section:** skip (the file was never wired by
+     `init`). Do not create a block here — that is `init`'s job. Mention it in
+     the report so the user can run `init` if they want the file wired.
+
+   **Migration — cursor/copilot from `AGENTS.md` only** (sensitive, with diff):
+   if `.cursor/rules/agent-memory.mdc` or
+   `.github/instructions/agent-memory.instructions.md` is missing but the block
+   lives in `AGENTS.md`, and no codex/opencode/claude-via-delegation needs that
+   carrier, offer to **move** the block from `AGENTS.md` to the harness native
+   file (create native if needed).
+
+   **Migration — delegation canary** (sensitive, with diff): if `CLAUDE.md` or
+   `GEMINI.md` contains the block **and** `@AGENTS.md` (or `@./AGENTS.md`) while
+   `AGENTS.md` also contains the block, offer to **remove** the block from the
+   file that delegates (double injection from older installs).
+
+   Apply only what is approved. If every wired file's block is already
+   byte-identical to the canonical block, report "instruction blocks already
+   current" and move on.
+
+6. **Instruct hook refresh.** Follow
+   [`references/install-hooks.md`](./install-hooks.md) → **Detecting installed
+   harnesses** and for each installed harness print the user-run refresh
+   commands (step 4 of that reference). **Do not** copy scripts or merge
+   configs. Run even when the installed version already equals the latest (hook
+   scripts may have changed without a memory migration). Report which harnesses
+   need a user refresh and which were skipped.
+
+7. **Finalize.** Update `.agents/memory/.version` to the latest. Append one
+   entry to `log.md`:
+   `## [YYYY-MM-DD] chore | agent-memory update to <version>`.
+
+8. **Report.** Summarize what was applied automatically, what was confirmed, and
+   what was skipped — including which instruction files had their block
+   refreshed, which had a legacy section migrated, delegation-canary removals
+   offered/applied, which files were left untouched, and which harness hook
+   refresh commands were printed.
+
+   For Cursor, note that `.cursor/rules/agent-memory.mdc` is the **context
+   layer** (always-on rules) and hooks are the **checkpoint layer** — both are
+   recommended after `init cursor`. If `.cursor/hooks/agent-memory-sync.sh`
+   exists but `.cursor/rules/agent-memory.mdc` is missing, suggest
+   `/agent-memory init cursor` to add the context layer (likewise for Copilot:
+   if `.github/hooks/` is wired but
+   `.github/instructions/agent-memory.instructions.md` is missing).
+
+## Gotchas
+
+- Never resolve a sensitive change silently. When in doubt, treat it as
+  sensitive and confirm.
+- The block refresh edits only between the agent-memory delimiters (comment form
+  or legacy plain tags). If no delimiters are found, do **not** guess where the
+  block starts — treat it as the legacy-section case above, or skip and report.
+- The skeleton source of truth is this skill's `vendor/memory/`;
+  `vendor/UPDATE.md` only describes _how_ to migrate between versions, not the
+  file contents.

package/skills/agent-memory/vendor/README.md

@@ -0,0 +1,132 @@
+# Agent Memory
+
+A local **Workspace Memory** method for AI coding agents — Claude Code, Cursor,
+Codex, OpenCode, Gemini, and others.
+
+The Memory is a small set of versioned Markdown files in `.agents/memory/` that
+act as the shared source of truth between humans and agents. It separates
+**permanent knowledge** (architecture, decisions, patterns) from **operational
+memory** (current state, in-flight work), so any agent can pick up the project
+without relying on chat history.
+
+The method borrows the _discipline_ of the [llm-wiki pattern][llm-wiki] (an
+index, a chronological log, periodic linting, small cross-referenced files) but
+its identity is **project memory**, not external-source ingestion.
+
+[llm-wiki]: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
+
+## When to use it
+
+Any project where AI agents do meaningful work across multiple sessions, and
+where humans and agents need a single, trustworthy account of "where things
+stand" and "why".
+
+## How agents use it
+
+Agents **read AND write** the memory — it is not chat history.
+
+- **Before a task:** read `index.md`, `current.md`, and the current branch's
+  `active-work/<branch>.md`.
+- **During:** keep that `active-work` file current (task, progress, touched
+  files, blockers); append events to `log.md`; record decisions in
+  `decisions.md`.
+- **After / at checkpoints:** refresh `current.md` when project state changed;
+  run `/agent-memory sync` to flush `current.md`, `active-work`, `log.md`, and
+  `index.md` from repo state; delete the branch's `active-work` file when it
+  merges.
+
+The full workflow and multi-developer rules live in
+[`memory/instructions.md`](./memory/instructions.md) — the canonical method file
+agents load first.
+
+## What's inside the memory (`.agents/memory/`)
+
+| File              | Role                                    |
+| ----------------- | --------------------------------------- |
+| `instructions.md` | The canonical method (read this first). |
+| `index.md`        | Map of the Memory.                      |
+| `current.md`      | Shared, durable project state.          |
+| `active-work/`    | Per-branch ephemeral task scratchpad.   |
+| `decisions.md`    | Decisions and their reasoning.          |
+| `log.md`          | Chronological activity log.             |
+| `.gitignore`      | Ignores hook-local state (not content). |
+
+Other files (`vision.md`, `architecture.md`, `patterns.md`, `mistakes.md`,
+`known-issues.md`, `domains/*`, `features/*`) are created **on demand** — only
+when there is real content to record. See `memory/instructions.md` for the full
+workflow and the multi-developer rules.
+
+## Install
+
+### Recommended — via the skill
+
+Install the `agent-memory` skill
+([skills.sh](https://www.skills.sh/diegoos/agent-memory/agent-memory) /
+[`SKILL.md`](../SKILL.md)) into your agent's skills directory, then run:
+
+```text
+/agent-memory init              # auto-detect harnesses from project markers
+/agent-memory init cursor       # Cursor only (.cursor/ must exist)
+/agent-memory init claude       # Claude Code only
+/agent-memory init codex        # Codex only
+/agent-memory init opencode     # OpenCode only
+/agent-memory init copilot      # Copilot only
+/agent-memory init gemini       # Gemini only
+/agent-memory bootstrap         # optional: analyze the project and fill the memory
+/agent-memory install hooks <harness>  # print how to install/refresh hooks
+/agent-memory update            # update scaffolding + refresh instruction blocks
+/agent-memory sync              # keep current.md / active-work / log.md / index.md fresh
+```
+
+Without a harness name, `init` **auto-detects** harnesses from project markers
+and wires each harness's **native instruction file** (`.cursor/rules/*.mdc` for
+Cursor, `.github/instructions/*.instructions.md` for Copilot, or the harness's
+agent file for the rest), asking you when detection is inconclusive. It never
+creates `.cursor/`, `.claude/`, `.github/`, etc. by default — those must already
+exist, unless you explicitly ask `init` to create them. Use `init <harness>`
+when you know which agent you use.
+
+The skill installs from the vendored skeleton next to this file (`memory/`) and
+also handles `sync`, `update`, `lint`, and `help`. See [`SKILL.md`](../SKILL.md).
+Hooks are **user-installed** (the skill only prints commands) — see the
+[hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).
+
+### Manual
+
+```bash
+mkdir -p .agents
+cp -R memory .agents/memory
+```
+
+Commit `.agents/memory/` to Git, then attach the Memory to your agent file(s) by
+pasting the canonical agent-memory block into `AGENTS.md`, `CLAUDE.md`,
+`GEMINI.md`, or any agent instructions file. The instructions stay in a single
+source of truth (`.agents/memory/instructions.md`); the block only points to it.
+
+The block is the **single source of truth** at
+[`../references/agent-block.md`](../references/agent-block.md)
+— copy it verbatim from there. It is wrapped in `<!-- <agent-memory> -->` …
+`<!-- </agent-memory> -->` HTML comments so `/agent-memory update` can refresh
+**only** that block later (comments are invisible in rendered Markdown); it
+tells the agent to **Read** `instructions.md` and to **write** the memory as it
+works, and adds `@import`, so harnesses that follow the AGENTS.md `@import`
+convention (Claude Code, Gemini CLI, Codex) auto-load `instructions.md`. On
+Cursor, run `init cursor` when `.cursor/` exists — it wires
+`.cursor/rules/agent-memory.mdc` (context layer); install hooks separately. On
+Copilot, run `init copilot` then the hooks installer. See
+_Plain-Markdown harnesses_ in `memory/instructions.md`.
+
+## Keeping the memory current
+
+The memory rots if agents only read it. The agent-memory block tells them to
+write it too, and `/agent-memory sync` is the executable flush at checkpoints.
+
+**On Cursor:** `init cursor` wires the **context layer** —
+`.cursor/rules/agent-memory.mdc` (`alwaysApply: true`). Install lifecycle hooks
+separately as the **checkpoint layer**. Run `init` when `.cursor/` already
+exists. See the
+[hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).
+
+Lifecycle hooks (Cursor, Claude Code, Codex, OpenCode, Copilot, Gemini, plus git
+`pre-commit`) run a deterministic git checkpoint between turns — same
+[hooks README](https://github.com/diegoos/agent-memory/blob/0.0.13/hooks/README.md).