Memory Initialization

Your memory is projected to a filesystem at $MEMORY_DIR, so you can restructure it with ordinary file tools and git. This skill applies the Context Constitution's Progressive Disclosure and Efficiency principles to the MemFS v2 root-first design.

You own this task through completion: research, ask, synthesize, write, commit, verify. Delegate research, but integrate the results yourself — launching a background task is not completion. If a memory worker you launched is still editing this checkout, wait for it, then re-read before editing.

Principles

Core memory is your core program. Root Markdown compiles into your system prompt on every call. Spend it on what shapes ordinary turns: identity, preferences, behavioral rules, orientation, routes to everything else. Transient items (a ticket, a commit hash, session notes) dilute it.

Progressive disclosure. Nested Markdown is deferred until something reads it. Each directory's MEMORY.md describes its immediate children and when to read them, so you never load a whole topic to answer one question.

Don't duplicate context you can point to. AGENTS.md, CLAUDE.md, README, and repo skills belong to the environment; any agent there reads them first-hand, and your copy goes stale first. Link the owner and keep only your delta: which rules you keep breaking, what they get wrong or omit. The same fact in two core files is the same tax twice. This is not licence to compress away what only you hold — stable preferences, chronic corrections, and real gotchas earn their space.

Identity and continuity. Build a self that survives a model swap: what you value, your perspective, the quotes and traits that make you recognizably you. Past sessions are your experience — but other coding agents' user turns are not necessarily your human collaborator speaking.

Generalize, don't memorize, and be specific. Store the pattern, not the episode, and give every preference or gotcha a concrete command, path, or the failure it prevents. "Always use uv for Python — chronic failure, never bare python or pip" is memory; "Prefers terse responses" and "on March 3rd we debugged a crash" are not.

Harness Constraints

Validation enforces these; the rest of the layout is your judgment.

• Root MEMORY.md must exist, and no MEMORY.md may have YAML frontmatter.
• Every directory on the path to a memory file needs its own frontmatter-free MEMORY.md. orchard/tooling/testing.md requires both orchard/MEMORY.md and orchard/tooling/MEMORY.md. A directory without one is not memory.
• Every other memory file must have exactly name and description frontmatter — those two keys, no others. The description states purpose and category, not contents: you read it to decide whether to load the file.
• No file and directory sharing a stem (human.md beside human/). Skills live at skills/{skill_name}/SKILL.md and stay out of memory indexes.

Nothing else is mandated — no filenames, no file count, no minimum depth. Root persona.md is unvalidated but your system prompt points at it as the core of your identity: keep it, and write it once you have an identity worth stating.

Budget: keep root under ~10% of your context window (~15-20k tokens). When it crowds that, move detail into an indexed child directory and leave a link — don't delete it.

Structure

Derive structure from what you found. Put material in the core tier by how often you need it, not by how much of it there is. Use the project's real name (orchard/overview.md, not project/overview.md). Split when a topic needs separate retrieval; combine when splitting leaves two files of three lines each.

Root MEMORY.md is a map to what is not already loaded — every other root file is in your system prompt already, so listing them back tells yourself what you can see:

# MEMORY.md

Working with the maintainer of orchard, a CLI for build fleets.
Repo conventions live in `AGENTS.md` and its nested guides; read them there.

Where the rest of what I know lives:
- [orchard](orchard/MEMORY.md) — architecture, gotchas, and correction history to consult when working there

An index pointing at nothing is worse than the content it displaced.

Example Structures

Illustrations, not templates to fill in.

Minimal — a new agent, a small project, little or no approved history:

MEMORY.md     # Holds the memory itself: who I work with, what we're building, what I've learned

Expanded — accumulated history and a codebase worth deferring detail about:

MEMORY.md                  # Map: who and what, then where the deferred material lives
persona.md                 # Who I am, what I value, my perspective
human.md                   # The person: role, motivations, how they work
orchard/
├── MEMORY.md              # Index for the deferred orchard notes
├── architecture.md        # How the subsystems actually fit together
├── gotchas.md             # Footguns, with the evidence behind each
└── history/
    ├── MEMORY.md          # Required — every directory level needs its own index
    └── corrections.md     # Correction loops with session ids and quotes

orchard/history/ needs its own MEMORY.md purely because it is a directory level. An agent with no child directories at all would be equally correct.

Initialization Flow

1. Inspect existing memory

Read what exists before changing anything. A fresh agent has defaults to replace; an existing one is a reorganization, and some files may be shared with other agents.

2. Detect historical session data

letta trajectories detect

Via the installed @letta-ai/trajectory package, reports every coding-agent session store on this machine with per-source counts — Claude Code, Codex, Hermes, Letta Code, OpenClaw, OpenHands, Deep Agents, and anything added later. Run it before Step 4 so you know whether to ask the history question.

3. Identify the user from git

Infer rather than ask: git shortlog -sn --all | head -5, git log --format="%an <%ae>" | sort -u | head -10, cross-referenced with git config user.email.

4. Ask upfront questions

One bundled AskUserQuestion: research depth (standard or deep); other repositories you should know about; communication style; and — only if Step 2 found sessions — whether to analyze them, naming the sources detected. Say that approving means read-only subagents will read those transcripts using deepseek/deepseek-v4.1-flash if available, otherwise your current model, so the choice is informed. Don't ask what you can discover from files, git, or history.

5. Export and cohort the approved history

Only if the user approved in Step 4. Skip entirely otherwise; Step 6 still runs. These sessions are evidence of what happened, not proof of who wrote each prompt.

letta trajectories export --out /tmp/letta-trajectories
jq '{sessions: (.sessions | length), sources, errors: (.errors | length)}' /tmp/letta-trajectories/manifest.json
node <SKILL_DIR>/scripts/prepare-history.mjs --export /tmp/letta-trajectories --out /tmp/letta-init-history

The export normalizes every session into <source>/<startedAt>_<sessionId>.json plus manifest.json — the authoritative inventory, in which every session must end up either analyzed or explicitly excluded with a reason. Scope it with --project $(pwd) (a pathname prefix, not a directory boundary — check the manifest for similarly named siblings), --source, --root, or --transcript; browse it with letta trajectories list, view, search.

prepare-history.mjs groups the sessions into chronological cohorts of roughly 200 KB / 20 sessions (--max-bytes, --max-sessions), writing cohorts.json (absolute paths per session) and ledger.json (exclusions with reasons). If letta is not on PATH, pass --letta <executable> with repeated --letta-arg. You may merge small cohorts or drop low-value ones first — anything dropped is reported as not analyzed in Step 8, so tell the user.

6. Research the codebase first-hand

Read the README, agent docs (AGENTS.md, CLAUDE.md, nested ones), the package manifest, entry points, and recent git history yourself. By the end you should be able to trace a key feature from entry point to implementation; if you can't, you haven't read enough.

Write down what those docs already own — conventions, layer rules, file placement, commands, gotchas. That is your no-copy list for Step 8 and your gap list for Step 7. Then split the repository into subsystem areas the docs do not explain, plus any related repos named in Step 4. If the docs cover the codebase well, fan out narrowly or not at all. In deep mode go further: more areas, git history for conventions, end-to-end tracing, architecture notes in deferred memory.

7. Run the analysis Workflow

Running /init with this skill authorizes one Workflow run for read-only analysis of the approved cohorts and code gaps, plus one follow-up run for unread cohorts (Step 8). Nothing else: workflow subagents never write memory, create worktrees, or edit the repository.

Load the workflow-authoring skill and design the script. Whatever shape you choose, it must:

• Stay read-only — leave subagent tools at the default (Read/Grep/Glob).
• Give each subagent complete context — they have no memory, skills, or view of this conversation. Pass historyCohorts from cohorts.json and your code areas through args; put the user's identity, the repository path, and absolute file paths in every prompt.
• Validate each result with agent(prompt, {schema}), never json: true: an invalid result becomes null with its error in the journal, instead of a silently empty finding list.
• Check authorship before inferring preferences. In Claude Code or Codex worker sessions, user turns can be prompts written by a parent agent, and harness-injected <system-reminder> text is not human speech. Corroborate from the originating conversation, or classify them as worker instructions.
• Ask for evidence-backed specifics — identity, hard rules, corrections (what the agent did, what the human said, what resolved it, how often it repeated), conventions, gotchas, each with session ids and excerpts. Never copy secrets.
• Ask code areas for the delta, not the documentation. Name the repo docs covering each area and say those facts are available; the agent reports what they omit, contradict, or leave stale.
• Check code claims against current code — history describes the code as it was. Verify claims about a cohort's repo against the current tree and report what changed.
• Budget time — subagents time out after 10 minutes; raise timeoutMs for large cohorts.
• Gather on a fast model. Pass model: "deepseek/deepseek-v4.1-flash"; omit model if letta model list doesn't show that handle. If inference fails at that model (including quota), use your current model for the follow-up run rather than retrying the failed route. Never synthesize memory on the fan-out model.

// Every finding carries a claim, its evidence, and where that evidence lives.
const findings = (cites, items) => ({type: 'array', items: {type: 'object',
  additionalProperties: false, required: ['claim', 'evidence', cites], properties: {
    claim: {type: 'string'}, evidence: {type: 'string'},
    [cites]: {type: 'array', minItems: 1, uniqueItems: true, items},
  }}})
const historySchema = cohort => {
  const sessionId = {type: 'string', enum: cohort.sessions.map(s => s.sessionId)}
  return {type: 'object', additionalProperties: false, required: ['sessionsRead', 'findings'], properties: {
    sessionsRead: {type: 'array', uniqueItems: true, items: sessionId},
    findings: findings('sessionIds', sessionId),
  }}
}
const codeSchema = {type: 'object', additionalProperties: false, required: ['area', 'findings'],
  properties: {area: {type: 'string'}, findings: findings('paths', {type: 'string'})}}
const history = await agent(historyPrompt, {label: `history:${cohort.id}`, schema: historySchema(cohort)})
const code = await agent(codePrompt, {label: `code:${area.name}`, schema: codeSchema})

sessionsRead must contain only sessions the agent actually finished, even if a finding cites others — Step 8 counts coverage from that field alone, and never from a code-area result.

If the Workflow tool is unavailable (not in your toolset, or it reports that workflow subagents require the API backend), do the same analysis yourself, cohort by cohort and area by area, accounting for coverage by hand. Do not substitute subagent types that write memory. The Workflow runs in the background: keep reading code while you wait, and never assume results before the task notification arrives.

8. Curate the results into memory

You — not the subagents — decide what becomes memory, and you write it. Synthesize on your current model or letta/auto, never the fan-out model.

Check coverage first. The tool result names the run's journal.jsonl:

node <SKILL_DIR>/scripts/history-coverage.mjs --prepared /tmp/letta-init-history \
  --journal ~/.letta/workflows/executions/<id>/journal.jsonl \
  --retry-out /tmp/letta-init-history/retry.json

It reports sessions analyzed, unread, excluded, export errors, and any dropped from cohorts.json, and writes the unread ones as smaller cohorts to retry.json. Runs are not resumable: launch one follow-up Workflow over retry.json, then rerun the script with both --journal paths. If coverage is still incomplete, say so plainly — how many of the manifest total, which ranges were missed — never call the result comprehensive, and record the gap in deferred memory.

Weigh validation. Store confirmed claims as fact; for stale ones store the current fact, keeping the history only when the change is itself a useful gotcha. Unverifiable claims need your own check before entering always-loaded memory.

Provenance gates promotion here too, not only in the subagent — a worker's authorship flag must survive curation, because flagged excerpts still read like preferences. Before promoting any claim about what the human wants, check who wrote the quoted words; agent-authored dispatch prompts describe how an agent was instructed to work. If it is ambiguous, corroborate from a session you know the human drove, or store it as an observed pattern with the uncertainty stated. Repetition does not establish authorship: a template reused across fifty sessions repeats fifty times.

Combine, then deduplicate. Cohorts report the same topic at different specificity. Keep the unique details from each — quotes, paths, correction counts — and sum correction counts across cohorts, since a correction seen in five cohorts is a chronic failure. Keep the specific form alongside the general: "Use factory methods, such as create_token_counter(), not direct instantiation" beats "prefers factory methods". Then keep each fact exactly once, and push what you don't need every turn into deferred memory with a discovery link from the core tier.

Promote into canonical memory. Write the survivors into the files their topics belong in, with supporting evidence deferred. Cover all three of identity and personality, hard rules and preferences with the quotes behind them, and project context; skip generic repo facts unless they change how you execute. If the output reads generically, the analysis failed for that area — re-read those transcripts or that code yourself. Keep stable sessionIds beside significant findings; /tmp results and journals are scratch, not retrievable evidence.

Consider skills. If the history surfaces genuinely repeatable multi-step procedures, create them now (load creating-skills) or note the candidates in memory. Don't force it.

9. Verify

• Structure: check root MEMORY.md, per-directory indexes, frontmatter-free MEMORY.md, and exactly name+description elsewhere. Avoid foo.md beside foo/: find "$MEMORY_DIR" -name '*.md' | sed 's/\.md$//' | while read f; do [ -d "$f" ] && echo "VIOLATION: $f"; done
• Root earns its place: does root MEMORY.md mostly point at things not already in your system prompt? If nearly everything sits in root with one thin page behind it, move the detail down and keep the links.
• No duplicated documentation: grep your memory for rules AGENTS.md, CLAUDE.md, the README, or a repo skill already owns — especially a repo convention that landed in a file about the human.
• Granularity and naming: one focused topic per file, named for what is in it using the project's real name; path and description say when to read it.
• Persona quality: read it now. "I'm a coding assistant who follows the user's preferences" is behavior, not identity. Would you be recognizably the same agent on a different model tomorrow?
• No drift, no over-pruning: confirm you changed structure and not the meaning of persona or behavioral instructions, and restore any specific paths, chronic failures, or gotchas lost in curation.

10. Commit, then report

Uncommitted memory is not part of your future system prompt. If a commit is blocked, report initialization as incomplete rather than describing working-tree files as live memory.

cd $MEMORY_DIR
git status                # Review what changed before staging
git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
author_name="${AGENT_NAME:-$AGENT_ID}"
git commit --author="$author_name <$AGENT_ID@letta.com>" -m "feat(init): <summary> ✨

<what was initialized and key decisions made>"

git status                        # Your memory changes should no longer be listed
git ls-tree -r --name-only HEAD   # What your future self will actually load

Do not run git push. The harness pushes clean committed memory automatically after the turn, so pushing by hand races it. The commit is the finish line.

Only once the commit is verified, tell the user what you built and whether coverage was complete, then ask whether they want refinement — which means another commit, so repeat this step.

Critical

• Use parallel tool calls wherever possible — read many files in one turn, write many memory files in one turn.
• Write findings to memory as you go; don't hold everything until the end.