Write Agent Memory System Review

Type: kb/types/instruction.md

Use this local skill to write or update type: kb/agent-memory-systems/types/agent-memory-system-review.md notes for external systems under kb/agent-memory-systems/reviews/.

This is a local commonplace-repo workflow, not a promoted cp-skill-* framework skill. The parent agent owns GitHub handling, local source directory setup, artifact lifecycle, QA, validation, indexes, and the final report. Delegate the code-grounded review drafting to a fresh worker context whenever the harness has a sub-agent mechanism.

Prerequisites

  • The topic is a GitHub repository reference: owner/repo or https://github.com/owner/repo.
  • The repository is reachable.
  • The checkout lives under related-systems/, outside kb/.

If the system has no reachable source code, stop and write a source-only note instead.

Steps

  1. Normalize the repository target. Derive:
  2. repo_url - canonical full GitHub repository URL for citations, https://github.com/{owner}/{repo} with no trailing slash or .git
  3. owner - GitHub owner or organization
  4. repo_name - final path segment
  5. repo_slug - default review slug, usually repo_name
  6. checkout_slug - owner-qualified checkout slug: {owner}--{repo_name}
  7. checkout_dir - related-systems/{checkout_slug}/
  8. source_dir - same path as checkout_dir; this is the directory passed to the review type contract

  9. note_path - kb/agent-memory-systems/reviews/{repo_slug}.md

  10. Resolve same-name collisions. Use the repository name as the default review filename unless there is already an established house-style variant. If kb/agent-memory-systems/reviews/{repo_name}.md already exists for a different GitHub repository with the same final path segment, use kb/agent-memory-systems/reviews/{owner}--{repo_name}.md. Do not overwrite or update a same-name review unless its **Repository:** line or frontmatter resolves to the same owner/repo.

  11. Choose the checkout path. Use the owner-qualified checkout directory for new clones. Existing reviews may have legacy basename-only checkouts such as related-systems/{repo_name}/; use a legacy checkout only when its origin remote resolves to the same GitHub owner/repo you are reviewing. If a legacy checkout points to a different owner with the same repository name, do not pull it, delete it, or repurpose it; clone the requested repo into the owner-qualified checkout_dir.

  12. Check main repo state. Run git status --short in the main repo before cloning or writing so you know whether unrelated changes already exist.

  13. Clone or refresh. If checkout_dir does not exist: bash git clone "{repo_url}" "{checkout_dir}" If checkout_dir exists: bash cd "{checkout_dir}" git fetch --all --prune git status --short git pull --ff-only If the pull cannot fast-forward because of local commits or conflicts, stop and report the state. Do not force, delete, or overwrite an existing checkout.

  14. Capture source metadata. Record the top-level listing, most recent commit, README, and package/manifest files for the writer's context. The parent establishes GitHub-specific metadata before delegation:

  15. source_dir: checkout_dir
  16. source_url: repo_url
  17. reviewed_commit: output of git -C "{checkout_dir}" rev-parse HEAD
  18. commit_url: {repo_url}/commit/{reviewed_commit}
  19. citation format:
    • files: {repo_url}/blob/{reviewed_commit}/{path}
    • directories: {repo_url}/tree/{reviewed_commit}/{path}

Write the refresh marker immediately after a successful clone/fetch/pull: bash git_dir="$(git -C "{checkout_dir}" rev-parse --absolute-git-dir)" date -Iseconds > "$git_dir/commonplace-checkout-refreshed-at" If the marker is more than 1 hour old by the time drafting starts, carry a checkout freshness warning into the final report. If it is more than 24 hours old, refresh again before drafting.

  1. Archive an existing review before writing. If note_path exists, archive it before drafting or delegating: bash git mv "{note_path}" "{note_path%.md}.replaced.{YYYY-MM-DD}.md" Then mark the archived file:
  2. Set status: outdated in frontmatter.
  3. Change tags: [related-systems, trace-derived] to tags: [].

  4. Add after the title: > Replaced {YYYY-MM-DD}. See [{name}](./{name}.md) for the current review. Do not read the archived .replaced.*.md file while writing the replacement.

  5. Draft the review by delegation. Use kb/agent-memory-systems/types/agent-memory-system-review.md as the worker's artifact contract. Its embedded comparison lens is the review-time distillation of the memory-system design; do not ask the worker to load the full design note during ordinary review writing.

Launch one fresh sub-agent or worker with a minimal task-local context. Do not fork the parent's full context when the harness offers a clean-context option. Give the worker only the local skill handoff, the type contract path, the source directory, the target note path, and the source metadata listed below.

The worker has only this ownership: - read kb/agent-memory-systems/COLLECTION.md - read kb/agent-memory-systems/types/agent-memory-system-review.md - read 1-2 current reviews for style - inspect source_dir - write note_path - decide trace-derived status from implementation evidence and either include both the placement section and trace-derived tag, or omit both

Pass the worker these type-contract inputs: - source_dir - note_path

Also pass this parent-supplied source metadata for the review note: - source_url - reviewed_commit - commit_url - citation format for files and directories

The worker must not edit indexes, archived reviews, the trace-derived survey, checkout state, or unrelated files. The parent owns checkout, archive moves, curated index edits, semantic QA, validation, and final report.

If the harness cannot launch a sub-agent or worker, stop after setup and report that delegated drafting is unavailable. Do not draft locally unless the user explicitly authorizes a local fallback for this run. If the user authorizes that fallback, report drafting was local, not delegated as a workflow exception.

  1. Update the curated index. If this is a new review, update kb/agent-memory-systems/README.md:
  2. add the system to the ## Systems list

  3. update ## Patterns Across Systems only if this repo adds a genuinely new cross-system pattern Keep the edit minimal and specific.

  4. Update the trace-derived survey if needed. If the review's trace-derived placement adds meaningfully to the survey, update kb/agent-memory-systems/trace-derived-learning-techniques-in-related-systems.md.

  5. Run semantic QA. Run the procedure from kb/instructions/run-review-bundle-on-note.md on the new review note using the semantic bundle. Treat it as a read-only QA loop: extract findings, fix clearly valid issues, and leave uncertain findings for the final report rather than forcing a rewrite.

  6. Validate. Run: bash commonplace-validate "{note_path}" If validation reports structural or description-quality issues, fix them and validate once more.

Report

Report:

  • repo cloned or reused
  • checkout freshness warning, if any
  • review path
  • whether drafting was delegated
  • whether the curated index changed
  • whether trace-derived-learning-techniques-in-related-systems.md changed
  • semantic gate bundle outcome
  • final commonplace-validate result

Constraints

Always:

  • keep checkouts under related-systems/
  • use owner-qualified checkout directories for new clones
  • write reviews under kb/agent-memory-systems/reviews/
  • cite repo source files with GitHub URLs pinned to the commit derived from the checkout
  • run semantic QA before final validation

Never:

  • put checked-out repos under kb/
  • overwrite or repurpose an existing checkout whose remote points to a different owner/repo
  • force-pull, delete, or reset a checkout to handle conflicts
  • leave the review unvalidated