Memory

Memory

Persistent per-role memory as plain markdown. You — the agent — read and write these files directly using your Read, Write, Edit, and Glob tools. No CLI, no script, no shell-path fragility. Works on any host, from any working directory.

File layout

Under .agents/memory// (where ` matches your agent's name: frontmatter — e.g. project-manager, python-dev, scout`):

.agents/memory//
├── MEMORY.md                ← curated index, one line per entry
├── .md                ← individual curated entries (frontmatter + body)
├── project_briefing.md      ← seeded by scout at install time (type: project)
├── daily/
│   └── YYYY-MM-DD.md        ← episodic daily logs, append-only
└── snapshot.md              ← auto-generated on launch (may be absent)

Create directories with mkdir -p on first use. Do not touch snapshot.md — the host's launch hook owns it. If it's absent, that's fine: you read memory directly when you need it.

.agents/ is an IDE-neutral path so the same memory works whether this agent is running under Claude Code, Cursor, Gemini CLI, Windsurf, or Copilot CLI.

Legacy paths (one-time migration)

If you find memory under one of these older locations and .agents/memory// doesn't exist, migrate it before your first write:

| Old location | New location | |---|---| | .claude/memory// (directory) | .agents/memory// — move the whole dir | | .agents-legacy/memory// (directory, older install) | .agents/memory// — move the whole dir | | .claude/memory/.md (flat file, from the former project-seeder skill) | .agents/memory//project_briefing.md — wrap the existing content with type: project frontmatter (see "Write" op below), add one index line to MEMORY.md |

Migrate with Bash (mv for directories) or Read/Write (for the flat file → curated entry conversion). Do this once; afterwards ignore the old paths.

Two stores, two purposes

| Store | When to use | Cost | Example | |---|---|---|---| | Daily log | Anything today's you would want tomorrow's you to know. Episodic, transient, cheap. | 1 line appended | "User pushed back on adding a new flag; wants to reuse existing config key" | | Curated entry | Durable facts, preferences, decisions, references. Should still be useful in 6 months. | 1 index slot | User's timezone; a validated correction about testing strategy |

If unsure: log it. You can promote to a curated entry later. Never the reverse.

Four curated types

Every curated entry carries a type: field:

| Type | Holds | |---|---| | user | Who the user is — role, expertise, preferences, working style | | feedback | Corrections and validated approaches. Always include why | | project | Goals, deadlines, constraints, in-flight initiatives. Decays fast — re-verify before acting. Scout seeds one here at install time (project_briefing.md) covering stack, conventions, and role-specific gotchas. | | reference | Pointers to external systems (Linear projects, Slack channels, dashboards) |

---

Operations

Log — append to today's daily log

To record ``:

1. Determine today's date. Use the Today's date is … line in your

environment context. If not present, run date -u +%Y-%m-%d.

1. Target path: .agents/memory//daily/.md.
2. If the file does not exist, Write it:

``` # Daily log —

• [HH:MM]

```

1. If the file already exists, Edit to append a single new line at

the end: - [HH:MM] .

Use 24-hour HH:MM. One observation per line. Keep it terse — full sentences are fine; paragraphs belong in curated entries.

Write — create or replace a curated entry

To record a curated entry named ` with , , and `:

1. Slugify `: lowercase, replace non-alphanumerics with _`,

strip leading/trailing underscores. Example: User Timezone → user_timezone.

1. Target path: .agents/memory//.md.
2. Write the file with this exact frontmatter (name, description,

type are parsed by the snapshot generator — don't omit them, don't add extra keys, keep each on one line): ```markdown --- name: description: type: ---

```

1. Update the index at .agents/memory//MEMORY.md:

• If MEMORY.md doesn't exist, Write it:

```markdown # Memory index —

• [](.md) —

```

• If a line already refers to .md, Edit that single line

to the new description. One entry = one line, no duplicates.

• Otherwise, Edit to append one new line at the end:

- [](.md) — .

Read — recall memory on demand

1. If a snapshot was auto-imported (the @.agents/memory//snapshot.md

line at the top of your AGENT.md), you already have curated memory and recent daily logs in your context — don't re-read them.

1. If no snapshot loaded (first session on a fresh project, or host

without a launch hook), read memory directly:

• Read .agents/memory//MEMORY.md for the curated index.
• Read .agents/memory//.md for any entry the index

points you at. Scout's project_briefing.md is usually the most load-bearing on a new project.

• Glob .agents/memory//daily/*.md, sort by filename

descending, and Read the most recent 3 files.

Bounded recall keeps your context small — don't tail the whole daily log history.

Rename / delete

• Rename a curated entry: Write the new .md, remove the

old file, Edit MEMORY.md to replace the single line.

• Delete: remove .md, Edit MEMORY.md to drop its line.
• Never edit a daily-log entry after the fact. Log a correction as a

new line instead — the audit trail is the point.

---

What belongs in memory vs. somewhere else

• Memory — durable facts and ephemeral working notes that matter *to

you as an agent* across sessions: user preferences, project constraints, lessons from corrections, references to external systems.

• Not memory — anything a human other than you should be able to find.

That goes in the user's knowledge base (e.g. obsidian-vault), the project's docs, the issue tracker, or the code itself.

Some agents also keep role-specific operational state in this directory (e.g. personal-assistant's people-pending.md). That's fine — the layout is yours to extend, as long as MEMORY.md, .md, and daily/ follow the spec above.

---

Snapshot.md — host launch hook concern, not yours

snapshot.md is regenerated by the host's launch hook before each session. It inlines MEMORY.md, every curated entry body, and the last 3 days of daily logs into a single file that the agent's AGENT.md auto-imports via @.agents/memory//snapshot.md.

You never write snapshot.md yourself. If it's missing, the @import becomes a no-op and you fall back to on-demand reads — no error, no interruption.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arozumenko
• Source: arozumenko/sdlc-skills
• License: MIT

Install and usage instructions live in the source repository linked above.