armandli/agent-memory

agent-memory Skill

Detect Intent

Determine which path to follow based on the user's request:

• Setup / Scaffold — user wants to initialize the project structure (create directories, memory files, CLAUDE.md). Go to Path A.
• Memory Operations — user wants to read or write one of the four memory files. Go to Path B.

---

Path A — Setup / Scaffold

Step A1 — Verify Working Directory

Run pwd and git rev-parse --show-toplevel 2>/dev/null.

• If the git root differs from pwd, warn the user and stop. All paths must be relative to the repo root.

---

Step A2 — Create Directories

Run:

mkdir -p docs/memory docs/plans

Both are created with -p (no error if already present).

After creating directories, note to the user:

docs/plans/ is ready. Use /plant-plan after planning sessions to copy plan files here from ~/.claude/plans/.

---

Step A3 — Create Memory Files

Use Glob to check which files already exist: docs/memory/*.md.

For each file not already present, use the Write tool to create it:

• docs/memory/adr.md — content: # Architectural Decision Records
• docs/memory/config.md — content: # Project Configuration
• docs/memory/bug.md — content: # Bug Fix History
• docs/memory/issue.md — content: # Open Issues

Skip any file that already exists.

---

Step A4 — Create .claude/CLAUDE.md

Use Glob to check whether .claude/CLAUDE.md already exists.

Only if it does not exist:

1. Run mkdir -p .claude to ensure the directory is present.
2. Use the Write tool to create .claude/CLAUDE.md with this exact content:

# Agent Memory

This project uses structured memory files to maintain context across sessions.

## Architecture Decisions

When making changes to project architecture or significant design decisions, read and update `docs/memory/adr.md` to record the decision, rationale, and consequences.

## Configuration and Settings

When changing project configurations or settings, read and update `docs/memory/config.md` to reflect the current configuration state.

## Bug Tracking

When fixing bugs:
- Check `docs/memory/bug.md` for historical bug fixes that may be relevant.
- After fixing a bug, record the fix and its root cause in `docs/memory/bug.md`.
- Check `docs/memory/issue.md` for currently open issues.
- When resolving an open issue, move it from `docs/memory/issue.md` to `docs/memory/bug.md`.

If .claude/CLAUDE.md already exists, skip creation.

---

Step A5 — Report

Print a summary listing:

• Directories created (or already existed)
• Each memory file: created or already present
• .claude/CLAUDE.md: created or skipped (already exists)

---

Path B — Memory Operations

Step B1 — Identify Intent and Read Target File(s)

Determine which operation is requested from the table below, then read all target files before making any edits.

| Intent | Target file(s) | |---|---| | Add architectural decision | docs/memory/adr.md | | Add/update config entry | docs/memory/config.md | | Add bug fix record | docs/memory/bug.md | | Add open issue | docs/memory/issue.md | | Resolve issue (move to bug) | docs/memory/issue.md + docs/memory/bug.md |

---

Step B2 — Apply File-Specific Schema

adr.md — Architectural Decision Records

Maintain as a Markdown table with exactly these 5 columns in order:

| ID/Name | Context | Decision | Alternative | Consequence | |---|---|---|---|---|

• ID/Name: a short unique identifier (e.g., ADR-001) and/or a descriptive name.
• Context: why this decision is needed — the problem or constraint driving it.
• Decision: what was chosen.
• Alternative: other options that were considered but not chosen.
• Consequence: trade-offs, risks, or downstream effects of the decision.

Append new rows; never delete existing rows.

---

config.md — Project Configuration

Free-form Markdown organized by service or category. Each entry should document one of:

• Hostnames or URLs
• Port numbers
• Service account email addresses
• Environment names (e.g., staging, prod)
• Public API endpoints
• Non-secret configuration values (feature flags, timeouts, limits)

NEVER record in this file:

• Authentication credentials or passwords
• Service account private keys or JSON key files
• OAuth client secrets or tokens
• Database connection strings with credentials
• Infrastructure secrets (API keys, certificates, private keys)

If the user attempts to write forbidden content, stop, warn them, and omit the secret.

---

bug.md — Bug Fix History

Maintain as a Markdown table with exactly these 5 columns in order:

| Date | Issue | Cause | Solution | Prevention | |---|---|---|---|---|

• Date: ISO 8601 date the bug was found (YYYY-MM-DD).
• Issue: nature or symptom of the bug.
• Cause: root cause — why it happened.
• Solution: how it was fixed.
• Prevention: how to avoid recurrence (can be left as — if not applicable).

Append new rows; never delete existing rows.

---

issue.md — Open Issues

Maintain as a Markdown table with exactly these 2 columns in order:

| Date | Issue | |---|---|

• Date: ISO 8601 date the issue was found (YYYY-MM-DD).
• Issue: nature or description of the problem.

Append new rows for new issues.

---

Step B3 — Issue Resolution Lifecycle

When an issue is resolved (user says the bug is fixed, issue is closed, etc.):

1. Read docs/memory/issue.md and identify the matching row.
2. Read docs/memory/bug.md.
3. Remove the resolved row from issue.md.
4. Append a new row to bug.md using:
   • Date: the date from issue.md (date found), not today's date.
   • Issue: the issue description from issue.md.
   • Cause: provided by the user or inferred from context.
   • Solution: provided by the user or inferred from context.
   • Prevention: provided by the user or — if not given.
5. Write both files.

If cause or solution is unknown, ask the user before writing.

---

Step B4 — Write Back

Use the Edit tool (not Write) to make targeted updates so existing content is preserved.

• For table files (adr.md, bug.md, issue.md): append new rows at the bottom of the table.
• For config.md: append under the relevant section heading, or create a new section.
• Never truncate or overwrite content that was not part of the requested change.
• If a table header row is missing from a file, add it before appending data rows.

---

Step B5 — Report

After every operation, confirm:

• Which file(s) were updated
• What was added or removed (one-line summary per change)
• If any forbidden config content was omitted, name what was excluded and why

---

Safety Rules

• Never write secrets or credentials to any memory file
• Never delete rows from adr.md or bug.md (append-only)
• Never delete rows from issue.md except when promoting to bug.md
• Always read before writing — do not overwrite content blindly
• If a table header row is missing from a file, add it before appending data rows

---

Final Step — Record Usage

After the skill's primary task completes, run:

python3 ${PWD}/.claude/skills/skill-stat/scripts/record-stat.py "agent-memory"