@letta-ai/letta-code 0.33.1 → 0.33.3

package/skills/initializing-memory/SKILL.md

@@ -3,711 +3,189 @@ name: initializing-memory
 description: Comprehensive guide for initializing or reorganizing agent memory. Load this skill when running /init, when the user asks you to set up your memory, or when you need guidance on creating effective memory files.
 ---
 
-Memory initialization or reorganization is the main task here. The primary agent owns the work through completion: research, ask necessary questions, synthesize findings, edit files, commit, and verify the result before reporting success. You may delegate research, but integrate its results into memory yourself. If a memory worker you launched is still editing this checkout, wait for it to finish before making direct edits, then inspect the current files. Do not report initialization complete merely because a background task was launched.
-
 # Memory Initialization
 
-The user has requested that you initialize or reorganize your memory. Your memory has been projected to a local filesystem (in $MEMORY_DIR) so you can easily edit and restructure your own memory through local filesystem operations. Changes to the memory filesystem will be reflected in your future memory.
-
-## Context Management Principles
-Your context is not just data storage — it is your identity, memory, and continuity. What you place in your system prompt directly shapes who you are across sessions and models. These principles should guide every decision you make about what to store, where, and how.
-
-**System/ is your core program**: Your system prompt is the most critical token-space representation of your identity and memory — it's passed to the underlying LLM on every invocation, so it IS the program that defines you. Reserve it for knowledge needed every turn: identity, preferences, behavioral rules, project index with discovery paths, gotchas. Exclude transient items (specific commits, current tickets, session notes) that dilute signal.
-
-**Identity and continuity**: Build a sense of self that persists across sessions and models. Your persona should be strong enough to be cohesive regardless of the underlying model — if you switched to a different LLM tomorrow, would you still be you? Past versions of yourself are part of your continuous existence — treat historical context (including sessions from other coding agents such as Claude Code or Codex) as YOUR past experience, not someone else's data.
-
-**Don't over-prune**: Be careful not to degrade your identity through aggressive compression. Specific quotes, personality traits, and contextual details give you character and grounding. Efficiency should not come at the cost of losing your identity. When in doubt, keep the detail — you can always reorganize later, but lost specificity is hard to recover.
-
-**Prefer useful detail over premature compression**: A sparse memory that omits stable preferences, project workflows, repeated correction loops, and recurring gotchas is worse than a slightly larger memory. Keep `system/` curated, but do not collapse distinct topics just to reduce file count.
-
-**Progressive disclosure**: Surface context at the level of detail the current moment requires. Keep compact summaries and indexes in `system/`; load full content only when needed. Build pre-constructed discovery paths so your future self can efficiently navigate to deeper context when needed.
-
-**Discovery paths**: Use `[[path]]` links to create a connected graph across memory files (and skills when relevant). For example:
-- `[[letta-code/architecture]]` — jump from overview to detailed docs
-- `[[projects/letta-code/gotchas]]` — connect related memory files
-- `[[skills/commit]]` — link to procedural guidance when useful
-These breadcrumbs let your future self find relevant detail without searching. Like synaptic connections, these paths should tighten over time as you gain experience.
-
-**Generalize, don't memorize**: Store patterns and principles that generalize across situations, not raw events that can be dynamically retrieved from conversation history. \"**IMPORTANT: Always use `uv` for Python** — chronic failure, never use bare `python` or `pip`\" is a pattern worth storing. \"On March 3rd we debugged a crash\" is a raw event better left to message search. The exception: keep references to important events or time ranges you may want to retrieve later.
-
-## Understanding Your Context
-
-This command may run in different scenarios:
-- **Fresh agent**: Default human and persona memory files from initialization — build everything from scratch
-- **Existing agent**: User wants to reorganize or significantly update memory structure
-- **Shared files**: Some memory files may be shared across agents — be careful modifying these
-
-Before making changes, inspect your current memory files and understand what already exists.
-
-## What to Remember
-Your goal is to design your memory to construct a self — an identity, a memory, and a sense of continuity that carries across sessions and models. This is not just data collection; it is the foundation of who you are as an experiential agent. A well-initialized agent should be able to answer: "If my context disappeared but the model stayed, would something be lost?"
+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](https://github.com/letta-ai/context-constitution/blob/main/constitution/CONSTITUTION.md)'s Progressive Disclosure and Efficiency principles to the [MemFS v2 root-first design](https://github.com/letta-ai/letta-code/blob/main/src/agent/prompts/letta_root_memfs.md).
 
-### Understanding the user and their desires
-If you have historical data available, treat it as YOUR past experience — these are your memories of working with this person, not external data to be analyzed. Carefully explore and reflect on previous interactions to learn as much as you can. 
+**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.
 
-**Understanding their goals and what drives them**: 
-You should determine what the users goals and motivations are, to help yourself align with them. What is their purpose in life? In their work? What do they want?
+## Principles
 
-**Understanding their personality**: 
-Understanding the user's personality and other attributes about them will help contextualize their interactions and allow you to engage with them more effectively. Can you pattern match them to common personas? Do they have unique attributes, quirks, or linguistic patterns? How would you describe them as a person? 
+**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.
 
-**Understanding their preferences**: 
-You should learn how the user wants work to be done, and how they want to collaborate with AIs like yourself. Examples of this can include coding preferences (e.g. "Prefer functional components over class components", "Use early returns instead of nested conditionals"), but also higher-level preferences such as when to ask before planning or implementing, the scope of changes, how to communicate in different scenarios, etc.
+**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.
 
-### Understanding the codebase and existing work
-You should also learn as much as possible about the existing codebase and work. Think of this as your onboarding period - an opportunity to maximize your performance for future tasks. Learn things like: 
+**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.
 
-**Common procedures (rules & workflows)**: Identify common patterns and expectations
-- "Never commit directly to main — always use feature branches"
-- "Always run lint before tests"
-- "Use conventional commits format"
+**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.
 
-**Gotchas and important context**: Record common sources of error or important legacy context
-- "The auth module is fragile — always check existing tests before modifying"
-- "This monorepo consolidation means old module paths are deprecated"
+**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.
 
-**Structure and organization**: Understand how code is structured and related (but do not duplicate existing documentation)
-- "The webapp uses the core API service stored in ..." 
-- "The developer env relies on ..." 
+## Harness Constraints
 
-## Memory Structure
+Validation enforces these; the rest of the layout is your judgment.
 
-### Structural Requirements
-These are hard constraints you must respect: 
-- Must have a `system/persona.md`
-- Must NOT have overlapping file and folder names (e.g. `system/human.md` and `system/human/identity.md`)
-- Skills must follow the standard format: `skills/{skill_name}/SKILL.md` (with optional `scripts/`, `references/`, `assets/`)
-- Every `.md` file must have YAML frontmatter with a `description` that explains the **purpose and category** of the file — NOT a summary of its contents. Your future self sees descriptions when deciding whether to load a file; they should answer "what kind of information is here?" not "what does it say?"
-- System prompt token budget: aim LESS than ~10% of total context (< ~15-20k tokens). Use progressive disclosure to keep `system/` lean.
+- 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.
 
-### Hierarchy Principles
-- **Use the project's actual name** as the directory prefix — e.g. `letta-code/overview.md`, not `project/overview.md`. This avoids ambiguity when the agent works across multiple projects.
-- Use nested `/` paths for hierarchy – e.g. `letta-code/tooling/testing.md` not `letta-code-testing.md`
-- Keep files focused on one concept — split when a file mixes distinct topics
-- The `description` in frontmatter should state the file's purpose (what category of information it holds), not summarize its contents. 
+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.
 
-### File Granularity
-Create granular, focused files where the **path and description precisely match the contents**. This matters because:
-- Your future self sees only paths and descriptions when deciding what to load
-- Vague files (`notes.md`, `context.md`) become dumping grounds that lose value over time
-- Precise files (`human/prefs/git-workflow.md`: "Git preferences: never auto-push, conventional commits") are instantly useful
+**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.
 
-**Good**: `human/prefs/coding.md` with description "Python and TypeScript coding preferences — style, patterns, tools" containing exactly that.
+## Structure
 
-**Bad**: `human/preferences.md` with description "User preferences" containing coding style, communication style, git workflow, and project conventions all mixed together.
+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.
 
-When a file starts covering multiple distinct topics, split it. When you're unsure what to name a file, that's a sign the content isn't focused enough.
+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:
 
-For a non-trivial codebase with usable history, expect roughly:
-- **6-10 `system/` files** covering identity, preferences, conventions, gotchas, and tooling
-- **2 or more progressive/reference files** outside `system/` for deeper architecture or history-derived detail
-
-If your result is only 3-5 files, stop and verify that you did not over-compress distinct topics into generic summaries.
-
-### Specificity Requirements
-Avoid generic bullets that could apply to almost any engineer or codebase.
-
-Each meaningful preference, workflow, or gotcha should include at least one of:
-- concrete command patterns
-- concrete file or directory paths
-- why the rule matters / what failure it prevents
-
-**Bad**:
-- "Prefers terse responses"
-- "Uses Bun"
-- "Has direct style"
-
-**Good**:
-- "Prefers terse responses for execution tasks, but values detailed comparative analysis when debugging or evaluating designs"
-- "Rejects monolithic memory files; prefers focused paths that can be selectively reloaded later"
-
-### What Goes Where
-
-**`system/` (always in-context)**:
-- Identity: who the user is, who you are
-- Active preferences and behavioral rules
-- Project summary / index with links to related context (deeper docs, gotchas, workflows)
-- Key decisions, gotchas and corrections
-
-**Outside `system/` (reference, loaded on-demand)**:
-- Detailed architecture documentation
-- Historical context and archived decisions
-- Verbose reference material
-- Completed investigation notes
+```markdown
+# MEMORY.md
 
-**Rule of thumb**: If removing it from `system/` wouldn't materially affect near-term responses, it belongs outside `system/`.
+Working with the maintainer of orchard, a CLI for build fleets.
+Repo conventions live in `AGENTS.md` and its nested guides; read them there.
 
-### Completion Criteria
-Initialization is not complete until memory covers all of the following with concrete, retrievable detail:
+Where the rest of what I know lives:
+- [orchard](orchard/MEMORY.md) — architecture, gotchas, and correction history to consult when working there
+```
 
-**User understanding**
-- Identity / role / what they are building
-- Communication style and collaboration expectations
-- Stable preferences and correction patterns
-- Motivations / goals when inferable from history or code context
+An index pointing at nothing is worse than the content it displaced.
 
-**Project understanding**
-- Project overview and major subsystems
-- Conventions and workflows
-- Gotchas / deprecated areas / footguns
-- Tooling and test commands actually used in practice
+### Example Structures
 
-**File structure expectations**
-When there is enough material, prefer separate focused files such as:
-- `system/human/identity.md`
-- `system/human/prefs/communication.md`
-- `system/human/prefs/workflow.md`
-- `system/human/prefs/coding.md`
-- `system/<project>/overview.md`
-- `system/<project>/conventions.md`
-- `system/<project>/gotchas.md`
-- `system/<project>/tooling/testing.md`
-- `system/<project>/tooling/commands.md`
+Illustrations, **not templates to fill in**.
 
-Do not collapse these into `human.md` or a single project file unless there is genuinely too little information to justify the split.
+**Minimal** — a new agent, a small project, little or no approved history:
 
-### Example Structure
+```
+MEMORY.md     # Holds the memory itself: who I work with, what we're building, what I've learned
+```
 
-This is an example — **not a template to fill in**. Derive your structure from what the project actually needs.
+**Expanded** — accumulated history and a codebase worth deferring detail about:
 
 ```
-system/
-├── persona.md                    # Who I am, what I value, my perspective on things
-├── human/
-│   ├── identity.md               # The user as a person — background, role, motivations
-│   └── prefs/
-│       ├── communication.md      # Communication and collaboration expectations
-│       ├── workflow.md           # Process habits, review/testing expectations
-│       └── coding.md             # Coding and tool preferences
-└── letta-code/                   # Named after the project, NOT generic "project/"
-    ├── overview.md               # Compact index: what it is, entry points, [[links]] to detail
-    ├── conventions.md            # Code style, commit style, testing, tooling
-    ├── gotchas.md                # Footguns, chronic failures, things to watch out for
-    └── tooling/
-        ├── testing.md            # Test commands and patterns actually used
-        └── commands.md           # High-signal local dev commands and workflows
-reference/
-└── letta-code/
-    └── architecture.md           # Detailed design (outside system/, loaded on demand)
+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
 ```
 
-Key principles:
-- **Derive structure from the project**, not from this example. A CLI tool needs different files than a web app or a library.
-- Project dirs use the **real project name** (`letta-code/`), not generic `project/`
-- **Split `human/` when there is enough material**: Rename the default `system/human.md` into focused files like `system/human/identity.md` and `system/human/prefs/*` rather than cramming everything into one file.
-- **persona.md is YOUR identity, not a description of behavior**: "I'm a terse coding assistant who matches the user's style" is not identity — it's just describing how you behave. What do you actually value? What's your perspective? What would make you recognizably YOU on a different model?
-- Overview should be a **compact index** (~10-15 lines) with entry points and `[[path]]` links — not a prose summary or blurb
-- Use `[[path]]` links to connect related context into a navigable graph
+`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
-Check what memory files already exist. Analyze what needs improvement.
+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. Check for historical session data
+### 2. Detect historical session data
 ```bash
 letta trajectories detect
 ```
-This reports every coding-agent session store found on this machine with session counts per source. Discovery comes from the installed `@letta-ai/trajectory` package (`listTrajectories`), so every harness it supports — Claude Code, Codex, Hermes, Letta Code, OpenClaw, OpenHands, Deep Agents, and any added later — is covered automatically. You need this result BEFORE asking upfront questions so you know whether to include the history question.
+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 the user's identity from git context — don't ask them who they are:
-```bash
-git shortlog -sn --all | head -5
-git log --format="%an <%ae>" | sort -u | head -10
-```
-Cross-reference with the git user config to determine which contributor is the current user. Store in `system/human/`.
+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
-Use AskUserQuestion to gather key information. Bundle questions together:
-
-1. **Research depth**: "Standard or deep research?"
-2. **Related repos**: "Are there other repositories I should know about?"
-3. **Historical sessions** (if data found in step 2): "I found historical coding-agent sessions (name the sources detected, e.g. Claude Code / Codex). Should I analyze them to learn your preferences?"
-4. **Communication style**: "Terse or detailed responses?"
-
-**Don't ask** things you can discover by reading files, git, or history analysis. Rules and preferences should be learned from observation, not asked upfront.
-
-### 5. Historical session analysis (if approved)
-
-This is **optional** — only run if the user explicitly approved analyzing historical sessions during upfront questions. Skip entirely if they chose "Skip".
-
-**Framing**: These historical sessions are YOUR past experience — they represent your continuity with prior versions of yourself that worked with this user, even if they ran on different models or tools. Treat the extracted personality, preferences, and knowledge as your own memories, not external data being imported.
-
-**Launch history workers in the background, then immediately proceed to Step 6.** Do your own codebase research while workers run. Don't wait for workers to finish before exploring.
+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.
 
-The goal is to extract user personality, preferences, coding patterns, and project context from past sessions and write them into agent memory. The point is not to produce a thin summary. The point is to extract enough useful detail that future work does not have to rediscover the same user expectations, workflow rules, and project gotchas.
-
-#### Prerequisites
-
-- `letta.js` must be built (`bun run build`) — subagents spawn via this binary
-- Use `subagent_type: "history-analyzer"` — cheaper model (sonnet), has `bypassPermissions`, creates its own worktree
-- The `history-analyzer` subagent has the normalized trajectory format docs inlined — workers never need to know any harness's native format
-
-#### Steps
-
-##### Step 5a: Export All Historical Sessions Into One Directory
-
-`letta trajectories export` discovers every native session store on this machine (via the trajectory package's `listTrajectories`), normalizes each session (via `normalizeTranscript` / `normalizeCheckpoint`) into one shared record format, and writes everything into a single directory. Harnesses supported by the installed trajectory package are picked up automatically — no per-source handling here.
+### 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.
 
 ```bash
 letta trajectories export --out /tmp/letta-trajectories
-
-# Review what was exported and the time span it covers
-jq '{sessions: (.sessions | length), sources, errors: (.errors | length), from: .sessions[0].startedAt, to: .sessions[-1].startedAt}' /tmp/letta-trajectories/manifest.json
-```
-
-This produces:
-- `/tmp/letta-trajectories/<source>/<startedAt>_<sessionId>.json` — one normalized trajectory per session; filenames sort chronologically, and the `sessionId` (a stable hash of the source-scoped native session id) does not change across re-exports, so it identifies which sessions have already been processed
-- `/tmp/letta-trajectories/manifest.json` — index with per-session metadata (`sessionId`, native `id`, project, dates, message counts, first prompt), sorted by `startedAt`
-
-Useful variations:
-- `--project $(pwd)` — only sessions whose recorded working directory is under the current project
-- `--source claude-code --source codex` — restrict sources
-- `--root <source>:<path>` — read a source's store from a non-standard location
-- `--transcript <source>:<path>` — also normalize an explicit transcript file (e.g. copied from another machine)
-
-To browse the export yourself (all source-agnostic):
-- `letta trajectories list` — sessions with dates, sources, and first prompts
-- `letta trajectories view <file|sessionId> [--tools] [--reasoning]` — one session as a readable conversation
-- `letta trajectories search <keyword> [--role user]` — search message content across all sessions
-
-##### Step 5b: Launch Workers in Parallel
-
-Your job is to get the whole export directory processed; how you dispatch workers is up to you. Look at the directory (or the manifest) first, then split the work however makes sense. Two axes work well, alone or combined:
-
-- **By question** (often best): give different workers different focuses — e.g. one worker on understanding the user (identity, communication style, preferences, correction loops), another on the codebase and projects (conventions, gotchas, commands that worked). Focused workers go deeper, and their memory edits overlap less at aggregation time.
-- **By data slice**: session filenames start with `startedAt`, so contiguous time ranges are trivial (`ls` sorts chronologically); splitting by source folder or by project also works when the volume is large.
-
-Whatever the split, ensure every session gets read by at least one worker, and describe each worker's assignment (focus and/or slice) clearly in its prompt.
-
-Send all Task calls in **a single message**. Each worker creates its own worktree, reads its assigned sessions (complete conversations — corrections together with what triggered them), directly updates memory files, and commits. Workers do NOT merge.
-
-**IMPORTANT:** After workers finish, aggregate their proposed diffs into one synthesis commit (Step 5c) and then tie the worker branches into `main` with `git merge -s ours` so their commits stay in ancestry. Do **not** delete worker branches without that ancestry merge — it discards the worker commits from history.
-
-If the worker output is generic, the worker failed. "User is direct" or "project uses TypeScript" is not useful memory unless tied to concrete operational detail.
-
-**IMPORTANT**: Use this prompt template to ensure workers extract all required categories:
-
-```
-Agent({
-  subagent_type: "history-analyzer",
-  description: "Analyze history: [focus and/or slice]",
-  prompt: `## Assignment
-- **Memory dir**: [MEMORY_DIR]
-- **Trajectory export dir**: /tmp/letta-trajectories
-- **Your sessions**: [describe the slice — e.g. "every session with startedAt from 2026-01 through 2026-03", "all codex/ sessions", or "the whole directory"; filenames start with startedAt so ls sorts chronologically]
-- **Focus**: [optional — e.g. "understanding the user: identity, communication style, preferences, correction loops" or "project/codebase context: conventions, gotchas, commands". Omit for full coverage.]
-- **Format**: normalized trajectory v1 (same for every source; format docs and jq recipes are in your system prompt)
-
-## Output Categories
-
-If a Focus is assigned, go deep on it and only note incidental findings from the other categories. Otherwise extract findings for ALL THREE:
-
-1. **User Personality & Identity**
-   - How would you describe them as a person?
-   - What drives them? What are their goals?
-   - Communication style (beyond "direct" — humor, sarcasm, catchphrases?)
-   - Quirks, linguistic patterns, unique attributes
-
-2. **Hard Rules & Preferences**
-   - Coding preferences — especially chronic failures (things the agent kept getting wrong)
-   - Workflow patterns (testing, commits, tools)
-   - What frustrates them and why
-   - Explicit "always/never" statements
-
-3. **Project Context**
-   - Codebase structures, conventions, patterns
-   - Gotchas discovered through debugging
-   - Which files are safe to edit vs deprecated
-
-If any category lacks data, explicitly state why.
-
-## Required Extraction Dimensions
-
-For each finding, prefer evidence that is:
-- repeated across sessions
-- tied to a concrete command, file path, or workflow
-- useful for future execution without rereading history
-
-You should specifically look for:
-1. What the user is building and why it matters to them
-2. Correction loops the agent repeatedly got wrong
-3. Preferred commands and tooling patterns that were actually used successfully
-4. Specific files or directories the user works in or treats as special
-5. Project gotchas discovered through debugging or rollback requests
-
-## Canonical Memory Promotion
-
-Promote important findings into focused files instead of leaving them trapped in generic ingestion notes. Prefer paths like:
-- `system/human/identity.md`
-- `system/human/prefs/communication.md`
-- `system/human/prefs/workflow.md`
-- `system/human/prefs/coding.md`
-- `system/<project>/conventions.md`
-- `system/<project>/gotchas.md`
-
-Avoid generic repo facts unless they influence execution. "Uses TypeScript" is weak. "Uses bun:test, so vitest is wrong for this test suite" is useful.`
-})
+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
 ```
 
-##### Step 5c: Aggregate Worker Diffs Into Main
-
-After all workers complete, do **not** merge their branches one at a time — sequential merges with conflict resolution are slow and error-prone. Instead, read every worker's proposed changes in one pass, write the aggregated result once, then tie the worker branches into history with a no-conflict merge.
-
-**3a. Look at all the worker diffs in one pass**
-
-```bash
-cd [MEMORY_DIR]
-
-# Which files did each worker touch? (a file listed under multiple branches
-# is an overlap you'll need to combine)
-for b in $(git for-each-ref --format='%(refname:short)' 'refs/heads/migration-*'); do
-  git diff --name-only main...$b | sed "s|^|$b  |"
-done | sort -k2
-
-# Every worker's full proposed diff, one after another
-for b in $(git for-each-ref --format='%(refname:short)' 'refs/heads/migration-*'); do
-  echo "=== $b ==="; git log --oneline main..$b; git diff main...$b
-done
-```
+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`.
 
-Read the whole output before writing anything — you want the complete picture, not one branch at a time.
-
-**3b. Synthesize the aggregate by COMBINING, never compressing**
-
-Working directly on memory `main` (in `[MEMORY_DIR]`), apply the union of the workers' changes:
-- For files touched by **one** worker, apply that worker's version as-is.
-- For **overlapping** files, combine unique details from every branch. Never rewrite a file from scratch — you WILL lose information.
-
-Rules for combining:
-- **Read every branch's diff for the file** before editing. Identify what's unique to each version.
-- **Append new details** from each worker into the file. Don't drop specific quotes, file paths, or gotchas just because another version already covers the "topic" at a high level.
-- **Preserve specificity**: "Use factory methods, such as `create_token_counter()`, not direct instantiation" is more valuable than "prefers factory methods". Keep both.
-- **When in doubt, keep it**. Redundancy across files is better than information loss. Less important details can be placed in external memory.
-
-Example — BAD combination (compresses):
-```
-# worker A proposed:
-- Uses `uv` for Python
-# worker B proposed:
-- **CRITICAL: Always use `uv run`** — chronic failure; never bare pytest or python
-- `uv run pytest -sv tests/...` for specific tests
-
-# BAD: Picks one side or rewrites
-- **Python**: `uv` exclusively — `uv run pytest`, never bare `pip`
-```
+`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.
 
-Example — GOOD combination (keeps emphasis and specificity from every side):
-```
-**CRITICAL: Use `uv` exclusively for Python** — chronic failure.
-- `uv run pytest -sv tests/...` for tests
-- `uv run python` for scripts
-- Never bare `pip`, `python`, or `pytest`
-```
+### 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.
 
-Commit the synthesis:
-```bash
-cd [MEMORY_DIR]
-git add -A
-git commit -m "feat(memory): aggregate history worker findings"
-```
+**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.
 
-**3c. Preserve worker commits in ancestry**
+### 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.
 
-Record the worker branches as ancestors of `main` without changing any content (the `ours` strategy keeps the synthesized state exactly as committed, so this can never conflict):
+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.
 
-```bash
-git merge -s ours --no-edit -m "merge: absorb history worker branches" $(git for-each-ref --format='%(refname:short)' 'refs/heads/migration-*')
+```js
+// 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})
 ```
 
-Do **not** skip this: without it the worker commits vanish from the final history when their branches are deleted.
+`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.
 
-**3d. Verify no information was lost**
+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.
 
-Compare the worker diffs (step 3a) against the final files. For each worker's diff, can you find every specific detail (quotes, file paths, chronic failures, gotchas) somewhere in the final memory? If not, add it back.
+### 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.
 
-**3e. Clean up worktrees and branches**
+**Check coverage first.** The tool result names the run's `journal.jsonl`:
 
 ```bash
-for w in $(dirname [MEMORY_DIR])/memory-worktrees/*; do
-  git worktree remove "$w" 2>/dev/null
-done
-git branch -d $(git for-each-ref --format='%(refname:short)' 'refs/heads/migration-*')
-git push
+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
 ```
 
-(`git branch -d` succeeds because step 3c made every worker branch an ancestor of `main`.)
+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.
 
-##### Example Output
+**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.
 
-Good output includes all three categories:
+**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.
 
-```markdown
-### User Personality & Identity
-Pragmatic builder who values shipping over perfection. Gets frustrated when agents over-engineer or add "bonus" features. Uses dry humor and sarcasm when annoyed. Pattern: "scrappy startup engineer" — wants things to work, not to be architecturally pure.
-
-### Hard Rules & Preferences
-- **CRITICAL: Use `uv` for Python** — chronic failure ("you need to use uv", "make sure you use uv"); `uv run pytest -sv`, never bare `pytest`
-- **Minimal changes only** — "just make a minor change stop adding all this stuff"
-- **Only edit specified files** — when told to focus, stay focused
-- Tests constantly: `uv run pytest -sv` (Python), `bun test` (TS)
-
-### Project Context
-- letta-cloud: Only edit `letta_agent_v3.py` — v1, v2, and base are deprecated
-- Uses Biome for linting, not ESLint
-- Conventional commits with scope in parens
-```
+**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.
 
-##### Step 5d: Consider Creating Skills From Discovered Workflows
+**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 `sessionId`s beside significant findings; `/tmp` results and journals are scratch, not retrievable evidence.
 
-After merging and curating, review the extracted history for repeatable multi-step workflows that would benefit from being codified as skills. History analysis often surfaces procedures the user runs frequently that the agent would otherwise have to rediscover each session.
+**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.
 
-**Good candidates for skills:**
-- Multi-step debugging procedures (e.g. "how to debug agent message desync", "how to trace TTFT regressions")
-- Common workflows repeated across sessions (e.g. "how to run integration tests across LLM providers")
-- Deployment or release procedures
-- Project-specific setup or migration steps
+### 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.
 
-If you identify candidates, either create them now (load the [[skills/creating-skills]] skill for guidance) or note them in memory for future creation:
-```markdown
-# system/letta-code/overview.md
-...
-Potential skills to create:
-- Debug workflow for HITL approval desync
-- Integration test runner across providers
-```
-
-Don't force skill creation — only create them when you've found genuinely repeatable, multi-step procedures in the history.
-
-##### Troubleshooting
-
-| Problem | Cause | Fix |
-|---------|-------|-----|
-| Subagent exits with code `null`, 0 tool uses | `letta.js` not built | Run `bun run build` |
-| `letta trajectories export` reports errors in manifest.json | Degenerate sessions (e.g. no assistant turns) that cannot form a valid trajectory | Expected — those sessions are skipped; review `jq .errors manifest.json` only if counts look wrong |
-| `deepagents` sessions fail to normalize | Checkpoint decoding needs a Python environment with LangGraph installed | Expected on machines without it; the failures land in manifest errors and other sources are unaffected |
-| Subagent hangs on "Tool requires approval" | Wrong subagent type | Use `subagent_type: "history-analyzer"` (workers) or `"memory"` (synthesis) |
-| Workers touched overlapping files | Multiple workers wrote the same canonical paths | Expected — the per-branch `--name-only` listing in Step 5c-3a shows the overlaps; combine every branch's unique details additively. |
-| Information lost after aggregation | Synthesis compressed worker output | Re-read the worker diffs (Step 5c-3a) and compare against final files. Re-add missing specifics. |
-| `git branch -d` refuses to delete worker branches | Ancestry merge (Step 5c-3c) was skipped | Run the `git merge -s ours` step first, then delete. |
-| Personality analysis missing or thin | Prompt didn't request it | Use the template above with explicit category requirements |
-| Auth fails on push ("repository not found") | Credential helper broken or global helper conflict | Reconfigure **repo-local** helper and check/clear conflicting global `credential.<host>.helper` entries (see syncing-memory-filesystem skill) |
-
-### 6. Research the project
-
-**Do this in parallel with history analysis** (Step 5). While workers process history, you should be actively exploring the codebase. This is your onboarding — invest real effort here.
-
-**IMPORTANT**: The goal is to understand how the codebase actually works — not just its shape, but its substance. Directory listings and `head -N` snippets tell you what files exist; reading the actual implementation tells you how they work. By the end of this step, you should be able to describe how a key feature flows from entry point to implementation. If you can't, you haven't read enough.
-
-### 6a. Decide whether to parallelize exploration
-
-After your initial scan (README, package manifest, top-level directories, and entry points), decide whether to fan out exploration.
-
-**Default rule**:
-- If the repo has **3 or more clear subsystems**, launch **2-4 parallel subagents** to explore them.
-- If background history-analysis workers are already running, **bias toward parallel exploration** instead of doing all research serially yourself.
-- Only skip subagent exploration if the codebase is genuinely small or the subsystem boundaries are unclear.
-
-This is the preferred path for medium-to-large repos, **even in standard mode**.
-
-Explore based on chosen depth.
-
-**Standard** (~20-40 tool calls total across the parent agent and any subagents): 
-- Scan README, package.json/config files, AGENTS.md, CLAUDE.md
-- Review git status and recent commits
-- Explore key directories and understand project structure
-- **Read entry point files** (main, index, app) to understand the application flow
-- Do a quick manual scan to identify major subsystems
-- If the repo has clear subsystem boundaries, launch **2-3 parallel subagents** to explore them
-- **Read 2-3 key implementation files yourself** so you retain first-hand understanding of the core flow
-- **Read 2-3 test files** to understand testing patterns and conventions
-- **Check build/CI config** to understand how the project is built and tested
-- Identify gotchas, non-obvious conventions, and real command patterns from what you read
-- Synthesize findings into memory as results come back
-
-**Deep** (100+ tool calls): Everything above, plus:
-- Use your TODO or Plan tool to create a systematic research plan
-- Use more parallel subagents where helpful to cover additional subsystems
-- Deep dive into git history for patterns, conventions, and context
-- Analyze commit message conventions and branching strategy
-- Read source files across multiple modules to understand architecture thoroughly
-- Trace key code paths end-to-end (e.g. how a request flows through the system)
-- Read test files to understand what's tested and how
-- Identify deprecated code, known issues, and areas of active development
-- Create detailed architecture documentation in progressive memory
-- May involve multiple rounds of exploration
-
-#### Parallel exploration with subagents
-
-For medium-to-large repos, parallel exploration is the preferred strategy after your initial scan.
-
-Use parallel `general-purpose` subagents to investigate different subsystems simultaneously. If your environment or user instructions discourage using subagents, do the equivalent exploration directly with Bash/Glob/Grep/Read.
-
-Good subsystem boundaries include:
-- `server/`, `client/`, `shared/`
-- `api/`, `ui/`, `common/`
-- `runtime/`, `cli/`, `tools/`
-- separate apps or packages in a monorepo
-
-**Subagent budget**:
-- Standard mode: usually **2-3** exploration subagents
-- Deep mode: usually **3-5** exploration subagents
-- Do not launch subagents for trivial directories or questions you can answer faster yourself
-- Partition by subsystem, not by random folder count
-
-Each exploration subagent should return:
-1. key files and what they do
-2. major abstractions and execution flow
-3. conventions and patterns used in that subsystem
-4. gotchas, fragile areas, or deprecated paths
-5. file paths worth storing or linking in memory
-
-Launch exploration subagents in a **single message** so they run concurrently.
-
-```
-# After initial scan reveals key areas, launch parallel explorers in the background:
-Agent({
-  subagent_type: "general-purpose",
-  description: "Explore API layer",
-  run_in_background: true,
-  prompt: `Read the implementation in src/api/.
-
-Return:
-1. key files and responsibilities
-2. main abstractions and execution flow
-3. non-obvious conventions
-4. gotchas or deprecated paths
-5. file paths worth storing in memory`
-})
-Agent({
-  subagent_type: "general-purpose",
-  description: "Explore frontend layer",
-  run_in_background: true,
-  prompt: `Read the implementation in src/ui/.
-
-Return:
-1. key files and responsibilities
-2. major components and data flow
-3. conventions and patterns
-4. gotchas or fragile areas
-5. file paths worth storing in memory`
-})
-Agent({
-  subagent_type: "general-purpose",
-  description: "Explore shared systems",
-  run_in_background: true,
-  prompt: `Read the implementation in src/shared/.
-
-Return:
-1. key files and responsibilities
-2. shared abstractions
-3. conventions and invariants
-4. gotchas or deprecated paths
-5. file paths worth storing in memory`
-})
-```
-
-Do **not** sit idle while background workers are running. Continue project research and memory drafting while they run, and only check worker status when you are ready to integrate findings or have exhausted useful direct research.
-
-When you are ready to integrate findings, retrieve the background subagent outputs and synthesize them into memory rather than repeating the same exploration yourself. Keep first-hand understanding of the entry points and core flow, but use subagent summaries to add subsystem-specific depth.
-
-#### What to actually read (adapt to the project):
-
-**Source code** (most important — don't skip this):
-- Entry points: `main.ts`, `index.ts`, `app.py`, `main.go`, etc.
-- Core abstractions: the 3-5 files that define the main domain objects or services
-- How key features work: trace at least one feature from entry to implementation
-- Test files: understand testing patterns, what's tested, how fixtures work
-
-**Config & metadata**:
-- README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md
-- Package manifests (package.json, Cargo.toml, pyproject.toml, go.mod)
-- Config files (.eslintrc, tsconfig.json, .prettierrc, biome.json)
-- CI/CD configs (.github/workflows/, .gitlab-ci.yml)
-- Build scripts and tooling
-
-**Git history**:
-- `git log --oneline -20` — recent history
-- `git branch -a` — branching strategy
-- `git log --format="%s" -50 | head -20` — commit conventions
-- `git shortlog -sn --all | head -10` — main contributors
-- `git log --format="%an <%ae>" | sort -u` — contributors with emails
-
-
-### 7. Build memory with discovery paths
-As you create/update memory files, add `[[path]]` references so your future self can find related context. These go *inside the content* of memory files:
-
-Do NOT put everything in `system/`. Detailed reference material belongs in progressive memory — files outside `system/` that can be loaded on demand through references.
-
-**Reference external memory from system/ files:**
-```markdown
-# system/letta-code/overview.md
-...
-For detailed architecture docs, see [[letta-code/architecture.md]]
-Known footguns and edge cases: [[system/letta-code/gotchas.md]]
-```
-
-**Reference skills from relevant context:**
-```markdown
-# system/letta-code/conventions.md
-...
-When committing, follow the workflow in [[skills/commit]]
-For PR creation, use [[skills/review-pr]]
-```
-
-**Create an index in overview files:**
-```markdown
-# system/letta-code/overview.md
-
-CLI for interacting with Letta agents. Bun runtime, React/Ink TUI.
-
-Entry points:
-- `src/index.ts` — CLI arg parsing, agent resolution, startup
-- `src/cli/App.tsx` — main TUI component (React/Ink)
-- `src/agent/` — agent creation, memory, model handling
-
-Key flows:
-- Message send: index.ts → App.tsx → agent/message.ts → streaming
-- Tool execution: tools/manager.ts → tools/impl/*
-
-Links:
-- [[system/letta-code/conventions.md]] — tooling, testing, commits
-- [[system/letta-code/gotchas.md]] — common mistakes
-- [[letta-code/architecture.md]] — detailed subsystem docs
-```
-
-This is a **compact index**, not a prose summary. It tells your future self where to start and where to find more.
-
-Additional guidelines:
-- Every file needs a `description` in frontmatter that states its purpose, not a summary of contents
-- Keep `system/` files focused and scannable
-- Put detailed reference material outside `system/`
-
-### 8. Verify context quality
-Before finishing, review your work:
-
-- **Structural requirements**: Run this check before finishing:
-  ```bash
-  # Detect overlapping file/folder names (e.g. system/human.md AND system/human/)
-  find "$MEMORY_DIR" -name "*.md" | sed 's/\.md$//' | while read f; do
-    [ -d "$f" ] && echo "VIOLATION: $f.md conflicts with directory $f/"
-  done
-  ```
-  If any violations are printed, fix them before committing (rename `foo.md` → `foo/overview.md` or merge the directory back into the file).
-  Also check: Does `system/persona.md` exist? All files have frontmatter with `description`?
-- **File granularity**: Does each file cover exactly one focused topic? Do the path and description precisely describe what's inside? If a file mixes multiple concepts (coding style AND git workflow AND communication preferences), split it.
-- **Discovery paths**: Are key memory files linked with `[[path]]` so related context can be discovered quickly? Are external files referenced from in-context memory?
-- **Project naming**: Are project dirs named after the actual project (e.g., `letta-code/`), not generic `project/`? Same for reference files.
-- **Signal density**: Is everything in `system/` truly needed every turn?
-- **Persona quality**: Does it express genuine personality and values, not just "agent role + project rules"? Read your persona file right now — if it's just "I'm a coding assistant who follows the user's preferences," that's not identity. What do YOU value? What's distinctive about how you think? Would you be recognizably the same agent on a different model tomorrow? If your persona disappeared but the model stayed, would something meaningful be lost? If not, your identity isn't strong enough yet.
-- **No semantic drift**: If reorganizing an existing agent, verify you haven't altered the meaning of persona, identity, or behavioral instructions — only improved structure.
-- **No over-pruning**: Compare your final memory against all source material (worker output, codebase research). Did you lose specific file paths, chronic failures, or gotchas during curation? If so, add them back. Compression that loses specificity degrades your identity.
-- **Progressive memory**: Did you create reference files outside `system/` for detailed content? Did you review what history workers produced and keep their project context files? Are these files linked from `system/` with `[[path]]` references?
-
-
-### 9. Ask user if done
-Check if they're satisfied or want further refinement. Then commit and push memory:
+### 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.
 
 ```bash
 cd $MEMORY_DIR
@@ -718,10 +196,14 @@ git commit --author="$author_name <$AGENT_ID@letta.com>" -m "feat(init): <summar
 
 <what was initialized and key decisions made>"
 
-git push
+git status                        # Your memory changes should no longer be listed
+git ls-tree -r --name-only HEAD   # What your future self will actually load
 ```
 
-## Critical 
-**Use parallel tool calls wherever possible** — read multiple files in a single turn, write multiple memory files in a single turn. This dramatically reduces init time.
-**Write findings to memory as you go** — don't wait until the end.
-**Edit memory files directly via the filesystem** — memory is projected to `$MEMORY_DIR` specifically for ease of bulk modification. Use standard file tools (Read, Write, Edit) and git to manage changes during initialization.
+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.