agent-memory

name: agent-memory description: "Save, recall, list, update, and organize repository working memories. Use when the user says or implies: 記憶して, 覚えておいて, 保存して, 思い出して, 前のメモを確認して, memory一覧, メモを探して, remember this, save this, recall, list memories, check notes, or when context should be preserved for resuming later."

Agent Memory

Use this skill to preserve and retrieve working context as Markdown files in the current repository.

Locate Memory Directory

Before saving, listing, or recalling memories:

1. Read the current repository's Rules.md (or CLAUDE.md if Rules.md does not exist).
2. Find the documented working-memory location.
3. Use that path as the memory directory.

For this life repository, Rules.md defines .agent/memories/.

If Rules.md does not define a memory directory, ask the user where to store memories. Do not silently choose a global location.

Safety

Treat repository memories as git-shared notes. Do not store secrets, directly abusable personal identifiers, unpublished research data, collaborator confidential information, or other material prohibited by the repository's rules.

Relationship to Claude Code's auto memory

Claude Code may also maintain per-machine auto memories under ~/.claude/projects/<project>/memory/. These two systems are complementary:

• agent-memory skill (this skill): git-shared, multi-machine, curated. Triggered by explicit user requests like 「記憶して」「思い出して」.
• Claude Code auto memory: per-machine, written automatically by Claude. Carries conversation context across sessions on the same machine.

Use agent-memory for facts that should follow the repo across machines and be visible in git. Use Claude Code auto memory for ephemeral conversation context private to this machine. The two do not need to be kept in sync.

Core Rule

Use a summary-first workflow.

1. Search memory summaries with rg.
2. Decide which files are relevant from frontmatter.
3. Read only the relevant memory files.
4. Save or update concise, self-contained Markdown notes.

Repository notes and user-facing Markdown should follow the language policy of the current repo. In life, write notes in Japanese unless the user asks otherwise.

For multi-machine setup, environment, or resume notes, avoid vague phrases such as "このPC". Prefer host <hostname> form, for example host kta38-Air. Get the short hostname with:

hostname -s

Search

Replace $MEMORY_DIR with the path from Rules.md.

rg "^summary:" "$MEMORY_DIR"
rg "^summary:.*keyword" "$MEMORY_DIR" -i
rg "^tags:.*keyword" "$MEMORY_DIR" -i
rg "keyword" "$MEMORY_DIR" -i

List

When the user asks to list memories, show a compact index before reading full files.

find "$MEMORY_DIR" -type f -name '*.md' | sort
rg "^(summary|created|updated|status|tags):" "$MEMORY_DIR" -n

Report each memory as:

- YYYY-MM-DD-short-topic.md: summary / status / tags

If there are more than 20 memory Markdown files, warn that the memory limit has been exceeded and propose consolidation.

Save

Save when the user asks to remember something, or when preserving context would clearly help resume later.

Before saving:

1. Count memory Markdown files with find "$MEMORY_DIR" -type f -name '*.md'.
2. Keep at most 20 memory Markdown files total unless the repository rules say otherwise.
3. If adding a new memory would exceed the limit, consolidate, delete obsolete content, or ask the user which memory to retire.
4. Check whether an existing memory should be updated instead of creating a new file.

Filename rule:

$MEMORY_DIR/YYYY-MM-DD-short-topic.md

Use the current local date. Use short lowercase kebab-case English or romanized topic words for the filename. Keep detailed Japanese text inside the Markdown body, not in the filename.

Required frontmatter:

---
summary: "Specific 1-2 line description of what this memory contains"
created: YYYY-MM-DD
---

Recommended optional fields:

updated: YYYY-MM-DD
status: in-progress # in-progress | resolved | blocked | abandoned
tags: [tag-one, tag-two]
related: [path/or/issue]

Recommended body sections:

# Title

## Context

## Decisions

## Current State

## Next Actions

Use only the sections that are useful. When machine-specific state matters, include the hostname in the relevant bullet or sentence rather than relying on relative wording like "this PC" or "other PC".

Recall

When the user asks to remember or check prior notes:

1. Search summaries first.
2. Search tags or full text only if summaries are insufficient.
3. Read the smallest set of relevant memory files.
4. Answer with the remembered facts, uncertainty, and where the memory came from.

Maintain

• Update memories when facts change; add or refresh updated.
• Mark stale work as resolved, blocked, or abandoned instead of silently leaving it ambiguous.
• Consolidate scattered memories on the same topic when they become hard to scan.
• Promote durable, shareable knowledge to normal repository areas when appropriate.

Auto-finalize

After saving, updating, or consolidating memory files, run the shared finalize script. It is a no-op unless AGENT_AUTO_COMMIT=1 is exported in the shell. On fenrir this is the default; on Air / mini-lab it is unset, so this call has no effect.

bash scripts/agent_auto_finalize.sh \
  -m "docs: 📝 agent-memory: <added|updated|consolidated> <short topic>" \
  .agent/memories/YYYY-MM-DD-<short-topic>.md

Pass every memory file you actually wrote or modified — if you consolidated several into one and deleted the originals, pass all of them so the deletions are also committed. The script commits with -o so other staged changes are not swept in.