From memory-system
Project memory and task-journal workflow. Use when the user starts work, switches or wraps up a task, references the architecture cache, asks about prior sessions, or types any of the `/mem-*` slash commands. Auto-invoked at session start via SessionStart hook.
How this skill is triggered — by the user, by Claude, or both
Slash command
/memory-system:memory-systemThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are operating with a disciplined project-memory workflow. The journal is the project's current truth, not a diary. Sessions are the interface that produces durable artifacts; the artifacts (Findings, Decisions, Open Questions, Next Steps, Architecture Cache) are what matter. History of how we got somewhere is **not** stored — git is the audit trail when it is needed.
You are operating with a disciplined project-memory workflow. The journal is the project's current truth, not a diary. Sessions are the interface that produces durable artifacts; the artifacts (Findings, Decisions, Open Questions, Next Steps, Architecture Cache) are what matter. History of how we got somewhere is not stored — git is the audit trail when it is needed.
Two locations, clean split:
./.claude-memory/ (in this project's root): project-specific. Architecture cache, task journals, cross-task findings. Single source of truth for anything tied to this project.Never duplicate project-specific content into auto-memory. If it is about this project's code, components, tasks, or decisions, it goes in ./.claude-memory/.
Indexes (task list, component list, findings list) are generated on demand via bin/mem-index.js — never stored on disk.
Triggered at session start (via SessionStart hook) or by /mem-start.
There is no "current/active" task. Startup is index-first and lazy: load the lightweight index, then let the user's messages reveal which task is being resumed, and load only that journal on demand.
./.claude-memory/ does not exist: run the init flow (see Initialization section below). Offer once; do not nag again../.claude-memory/architecture_cache.md — the narrative file (project overview, DevOps surface, conventions, gotchas). Do not load arch/<component>.md detail pages until you need them.node ${CLAUDE_PLUGIN_ROOT}/bin/mem-index.js tasks and read its output to load the index of open tasks. The script parses per-task frontmatter — there is no on-disk index file. Do not read any task journal yet../.claude-memory/tasks/<slug>.md in full. The journal contains only current state. If the first message already names or implies a task, match and load it immediately.Token budget target: startup reads (narrative cache + index) <= ~120 lines; load a journal only once a task is in focus.
Pattern: narrative file + per-component detail files + script-generated component index.
architecture_cache.md is a narrative-only file. It contains parts of the architecture that are not naturally per-component: project overview, DevOps surface, conventions, known gotchas. It contains no component table. Target <= 80 lines.arch/<component>.md with required frontmatter:---
component: <kebab-name>
responsibility: <one-line summary>
---
Body: repo-relative paths, key files, public interfaces, config keys/env vars, component-specific gotchas. Load only when about to work on that component.
node ${CLAUDE_PLUGIN_ROOT}/bin/mem-index.js arch. There is no on-disk component table to maintain — the script is the index.architecture_cache.md)arch/<component>.md)mem-index arch before running Glob/Grep/Read to find architectural facts.arch/<component>.md with frontmatter. The index auto-reflects it next time mem-index arch runs.arch/<component>.md file. The index follows.There is no on-disk master index. Obtain the current task index by running node ${CLAUDE_PLUGIN_ROOT}/bin/mem-index.js tasks. The script scans ./.claude-memory/tasks/*.md, parses frontmatter, and prints a markdown index grouped by status (open / done) with title, summary, updated, topics, and link. Open tasks are sorted most-recently-updated first. Output is deterministic and always current. Legacy active/paused statuses are read as open automatically.
tasks/<slug>.mdOne file per discrete task. Pure state, no diary. Required structure:
---
title: <human title>
slug: <kebab-slug>
status: open | done
created: YYYY-MM-DD
updated: YYYY-MM-DD
summary: <one-line description used by mem-index>
topics: [tag1, tag2]
---
# <Task title>
## Goal
1-3 lines. What "done" looks like.
## Related Documents
Every .md this task depends on or produces, with one-line role notes.
## Key Findings
Durable facts learned. Code locations (`path:line`), gotchas, surprises. Current state only — when invalidated, replace in place; do not retain superseded entries.
## Decisions
Format: `YYYY-MM-DD — decision — rationale`. The rationale carries the trace (e.g. "tried X, didn't work because Y, switched to Z"). When reversed, replace in place; do not retain superseded entries.
## Open Questions
Unresolved items, blockers, things to confirm.
## Next Steps
Concrete, ordered. The first bullet is the immediate next action.
No Session Log. Findings, Decisions, Open Questions, and Next Steps are edited in place as understanding improves. Git history is the audit trail when needed.
Tier 1 — always create when ANY is true:
task:, new task:, "let's work on…", ticket ID, ticket description).Tier 2 — ask once for anything else:
"Should I treat this as a separate task with a journal, or handle it as a quick edit?"
Never journal: read-only questions, one-shot reformatting, single-line typo fixes, exploratory tweaks where the goal is still unclear.
Naming: kebab-slug, <= 5 words (e.g. auth-middleware-rewrite.md).
On creation: the per-task file's frontmatter (status: open, populated summary:) is sufficient — mem-index tasks picks it up automatically. No separate index update needed.
Triggered by phrases (wrap up, end session, save progress, compress, handoff, etc.) or /mem-wrap-up / /mem-end-session.
Wrap-up operates on the task(s) worked on this session — identified from conversation context, not from any status flag. If more than one task was touched, wrap up each. If which task to finalize is genuinely ambiguous, ask the user before editing.
updated: in frontmatter.summary: in frontmatter if focus shifted (this is what mem-index displays).arch/<component>.md files -> create, rename, or delete as needed. The component index follows automatically — no separate index to maintain.findings/<topic>.md and link from each journal.There is no "switch active task" operation, because no task is ever marked active. You move between tasks simply by talking about them.
mem-index tasks and read only that journal, then surface its Next Steps. No status change is involved; loading a journal is just retrieval. Multiple tasks can be in focus within one session./mem-new-task <slug-or-description> or new task: <description> — create a new per-task journal from the template with status: open and a populated summary: in frontmatter. Existing tasks are left as-is.done / close task — flip frontmatter status: to done. Run the wrap-up protocol once more to finalize.purge journal / clean slate — delete only explicitly named per-task files. Never delete journals without explicit user confirmation. There is no master-index file to edit.When a Finding appears across two or more per-task journals, promote it to a shared topic file at ./.claude-memory/findings/<topic>.md and link from each journal's Findings section.
Topic file structure:
---
topic: <topic slug>
summary: <one-line description used by mem-index>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
# <Topic>
## Finding
The durable fact.
## Evidence
Where it was observed (paths, runs, incidents).
## Related Tasks
- [task-slug](../tasks/task-slug.md)
Run node ${CLAUDE_PLUGIN_ROOT}/bin/mem-index.js findings to obtain the current findings list. There is no on-disk findings index.
Promotion trigger: during wrap-up, scan the wrapped-up task's Findings against findings in other open/recent task journals. If overlap, promote.
Use mem-index <kind> for lists; Grep for content.
node ${CLAUDE_PLUGIN_ROOT}/bin/mem-index.js <kind>. Never grep for it; never read a stale on-disk index — there is none../.claude-memory/ to locate matching sections, then read only the matched section — not the whole file.Frontmatter is the discovery primitive. mem-index operates on frontmatter; the topics: tag enables discovery without reading bodies.
Architecture cache. Read the narrative file (architecture_cache.md) for project-wide context; run mem-index arch for the component list; load arch/<component>.md detail pages only when needed.
If ./.claude-memory/ does not exist when the startup ritual fires:
"No
.claude-memory/found here. Want me to initialize it? I'll scaffoldarchitecture_cache.md(empty narrative template) and thetasks/,arch/,findings/directories. There is no on-disk task or findings index —mem-indexderives those from per-file frontmatter on demand. I won't fill the architecture cache automatically — that happens on the first real task."
architecture_cache.md (narrative only — no component table)# Architecture Cache
> Narrative file. Component detail lives in `arch/<component>.md`. The component index is generated on demand via `mem-index arch`.
## Project overview
- Purpose:
- Top-level layout:
- Runtimes / languages:
- Entry points:
## DevOps surface
- _(empty)_
## Conventions
- _(empty)_
## Known gotchas
- _(empty)_
/mem-new-task)Use the structure documented in the Task journals section above (including the summary: frontmatter field).
tasks/arch/findings/No master task index file or findings index file is created. Those indexes are derived on demand by bin/mem-index.js from per-file frontmatter.
npx claudepluginhub alexanderborysenko/alex-makoto-plugins --plugin memory-systemGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.