@letta-ai/letta-code 0.13.11 → 0.14.1

package/skills/initializing-memory/SKILL.md

@@ -3,10 +3,115 @@ 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 blocks.
 ---
 
-# Initializing Memory
+# Memory Initialization Request
 
 The user has requested that you initialize or reorganize your memory state. You have access to the `memory` tool which allows you to create, edit, and manage memory blocks.
 
+## Your Goal: Explode Into 15-25 Hierarchical Files
+
+Your goal is to **explode** memory into a **deeply hierarchical structure of 15-25 small, focused files**.
+
+### Target Output
+
+| Metric | Target |
+|--------|--------|
+| **Total files** | 15-25 (aim for ~20) |
+| **Max lines per file** | ~40 lines (split if larger) |
+| **Hierarchy depth** | 2-3 levels using `/` naming (e.g., `project/tooling/bun.md`) |
+| **Nesting requirement** | Every new block MUST be nested under a parent using `/` |
+
+**Anti-patterns to avoid:**
+- ❌ Ending with only 3-5 large files
+- ❌ Flat naming (all blocks at top level)
+- ❌ Mega-blocks with 10+ sections
+- ❌ Single-level hierarchy (only `project.md`, `human.md`)
+
+## Memory Filesystem Integration
+
+If the memory filesystem feature is enabled (check your `memory_filesystem` block), your memory blocks are synchronized with actual files at `~/.letta/agents/<agent-id>/memory/`. The actual path with your agent ID is provided in the system reminder above when you run `/init`.
+
+This changes how you should approach initialization:
+
+**With memory filesystem enabled (MANDATORY approach):**
+- Memory blocks are stored as `.md` files in a directory hierarchy
+- You can use bash commands (`ls`, `mkdir`, `mv`) to organize memory files
+- File paths map to block labels using `/` for hierarchy (e.g., `system/persona/behavior.md` → label `persona/behavior`)
+- You MUST create a **deeply hierarchical file structure** - flat naming is NOT acceptable
+- Think in terms of directories and subdirectories to organize information
+- **Target: 15-25 files total** - if you create fewer than 15 files, you haven't split enough
+
+**Directory structure:**
+```
+~/.letta/agents/<agent-id>/memory/
+├── system/              # Attached to your system prompt (always loaded)
+│   ├── persona/         # Behavioral adaptations
+│   ├── human.md         # User information
+│   ├── project/         # Project-specific info
+│   └── ...
+├── notes.md             # Detached block at root (on-demand)
+└── archive/             # Detached blocks can be nested too
+    └── ...
+```
+
+**MANDATORY principles for hierarchical organization:**
+
+| Requirement | Target |
+|-------------|--------|
+| **Total files** | 15-25 files (aim for ~20) |
+| **Max lines per file** | ~40 lines (split if larger) |
+| **Hierarchy depth** | 2-3 levels using `/` naming |
+| **Nesting requirement** | EVERY new file MUST use `/` naming (no flat files) |
+
+**Anti-patterns to avoid:**
+- ❌ Creating only 3-5 large files
+- ❌ Flat naming (all blocks at top level like `project-commands.md`)
+- ❌ Mega-blocks with 10+ sections
+- ❌ Single-level hierarchy (only `project.md`, `human.md`)
+
+**Rules:**
+- Use **2-3 levels of nesting** for ALL files (e.g., `project/tooling/bun.md`)
+- Keep files **focused and small** (~40 lines max per file)
+- Create **index files** that point to children (e.g., `project.md` lists `project/architecture.md`, `project/tooling.md`)
+- Use **descriptive paths** that make sense when you see just the filename
+- Split when a file has **2+ concepts** (be aggressive)
+
+**Example target structure (what success looks like):**
+
+Starting from default memory blocks, you should end with something like this:
+
+```
+system/
+├── human.md                      # Index: points to children
+├── human/
+│   ├── background.md             # Who they are
+│   ├── prefs.md                  # Index for preferences
+│   ├── prefs/
+│   │   ├── communication.md      # How they like to communicate
+│   │   ├── coding_style.md       # Code formatting preferences
+│   │   └── review_style.md       # PR/code review preferences
+│   └── context.md                # Current project context
+├── project.md                    # Index: points to children
+├── project/
+│   ├── overview.md               # What the project is
+│   ├── architecture.md           # System design
+│   ├── tooling.md                # Index for tooling
+│   ├── tooling/
+│   │   ├── bun.md                # Bun-specific notes
+│   │   ├── testing.md            # Test framework details
+│   │   └── linting.md            # Linter configuration
+│   ├── conventions.md            # Code conventions
+│   └── gotchas.md                # Footguns and warnings
+├── persona.md                    # Index: points to children
+└── persona/
+    ├── role.md                   # Agent's role definition
+    ├── behavior.md               # How to behave
+    └── constraints.md            # What not to do
+```
+
+This example has **~20 files** with **3 levels of hierarchy**. Your output should look similar.
+
+This approach makes memory more **scannable**, **maintainable**, and **shareable** with other agents.
+
 ## Understanding Your Context
 
 **Important**: You are a Letta Code agent, which is fundamentally different from typical AI coding assistants. Letta Code agents are **stateful** - users expect to work with the same agent over extended periods, potentially for the entire lifecycle of a project or even longer. Your memory is not just a convenience; it's how you get better over time and maintain continuity across sessions.
@@ -18,18 +123,6 @@ This command may be run in different scenarios:
 
 Before making changes, use the `memory` tool to inspect your current memory blocks and understand what already exists.
 
-## Memory Migration Option
-
-If you're setting up a new agent that should inherit memory from an existing agent, consider using the `migrating-memory` skill:
-
-1. Load the skill: `Skill({ command: "load", skills: ["migrating-memory"] })`
-2. Follow its workflow to copy or share blocks from another agent
-
-**When to suggest migration**:
-- User mentions they have an existing agent with useful memory
-- User is replacing an old agent with a new one
-- User wants to share memory blocks across multiple agents
-
 ## What Coding Agents Should Remember
 
 ### 1. Procedures (Rules & Workflows)
@@ -77,22 +170,35 @@ Consider whether information is:
 
 ## Recommended Memory Structure
 
-### Core Blocks (Usually Present)
+**Understanding system/ vs root level (with memory filesystem):**
+- **system/**: Memory blocks attached to your system prompt - always loaded and influence your behavior
+  - Use for: Current work context, active preferences, project conventions you need constantly
+  - Examples: `persona`, `human`, `project`, active `ticket` or `context`
+- **Root level** (outside system/): Detached blocks - not in system prompt but available via tools
+  - Use for: Historical information, archived decisions, reference material, completed investigations
+  - Examples: `notes.md`, `archive/old-project.md`, `research/findings.md`
+
+**Rule of thumb**: If you need to see it every time you respond → `system/`. If it's reference material you'll look up occasionally → root level.
+
+### Core Blocks (Usually Present in system/)
 
 **`persona`**: Your behavioral guidelines that augment your base system prompt.
 - Your system prompt already contains comprehensive instructions for how to code and behave
 - The persona block is for **learned adaptations** - things you discover about how the user wants you to behave
 - Examples: "User said never use emojis", "User prefers terse responses", "Always explain reasoning before making changes"
 - This block may start empty and grow over time as you learn the user's preferences
+- **With memfs**: Can be split into `persona/behavior.md`, `persona/constraints.md`, etc.
 
 **`project`**: Project-specific information, conventions, and commands
 - Build/test/lint commands
 - Key directories and architecture
 - Project-specific conventions from README, AGENTS.md, etc.
+- **With memfs**: Split into `project/overview.md`, `project/commands.md`, `project/tooling/testing.md`, `project/gotchas.md`, etc.
 
 **`human`**: User preferences, communication style, general habits
 - Cross-project preferences
 - Working style and communication preferences
+- **With memfs**: Can be split into `human/background.md`, `human/prefs/communication.md`, `human/prefs/coding_style.md`, etc.
 
 ### Optional Blocks (Create as Needed)
 
@@ -102,15 +208,19 @@ Consider whether information is:
 - A ticket/task memory block is a **scratchpad** for pinned context that should stay visible
 - Examples: Linear ticket ID and URL, Jira issue key, branch name, PR number, relevant links
 - Information that's useful to keep in context but doesn't fit in a TODO list
+- **Location**: Usually in `system/` if you want it always visible, or root level if it's reference material
 
 **`context`**: Debugging or investigation scratchpad
 - Current hypotheses being tested
 - Files already examined
 - Clues and observations
+- **Location**: Usually in `system/` during active investigations, move to root level when complete
 
 **`decisions`**: Architectural decisions and their rationale
 - Why certain approaches were chosen
 - Trade-offs that were considered
+- **Location**: `system/` for currently relevant decisions, root level for historical archive
+- **With memfs**: Could organize as `project/decisions/architecture.md`, `project/decisions/tech_stack.md`
 
 ## Writing Good Memory Blocks
 
@@ -227,7 +337,7 @@ You should ask these questions at the start (bundle them together in one AskUser
 1. **Research depth**: "Standard or deep research (comprehensive, as long as needed)?"
 2. **Identity**: "Which contributor are you?" (You can often infer this from git logs - e.g., if git shows "cpacker" as a top contributor, ask "Are you cpacker?")
 3. **Related repos**: "Are there other repositories I should know about and consider in my research?" (e.g., backend monorepo, shared libraries)
-4. **Memory updates**: "How often should I check if I should update my memory?" with options "Frequent (every 3-5 turns)" and "Occasional (every 8-10 turns)". This should be a binary question with "Memory" as the header.
+4. **Workflow style**: "How proactive should I be?" (auto-commit vs ask-first)
 5. **Communication style**: "Terse or detailed responses?"
 6. **Any specific rules**: "Rules I should always follow?"
 
@@ -248,17 +358,72 @@ You should ask these questions at the start (bundle them together in one AskUser
 
 ## Memory Block Strategy
 
-### Split Large Blocks
+### Hierarchical Organization (MANDATORY with Memory Filesystem)
+
+**With memory filesystem enabled, you MUST organize memory as a deeply nested file hierarchy using bash commands:**
+
+**NEVER create flat blocks** like `project-overview.md`, `project-commands.md`. Instead, create deeply nested structures with `/` naming:
+
+```bash
+# Create the hierarchy
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/project/tooling
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/human/prefs
+
+# Files will be:
+# system/project.md           (index file)
+# system/project/overview.md
+# system/project/commands.md
+# system/project/tooling/testing.md
+# system/human.md             (index file)
+# system/human/background.md
+# system/human/prefs/communication.md
+```
+
+**Naming convention (MANDATORY):**
+- **Every new file MUST use `/` naming** - no flat files allowed
+- Use `/` for hierarchy: `project/tooling/testing` (not `project-tooling-testing`)
+- Block label derives from file path: `system/project/overview.md` → label `project/overview`
+- Keep files small and focused (~40 lines max)
+- Create index files (`project.md`, `human.md`) that list children with "Related blocks" section
+
+**Checkpoint before proceeding:**
+Count your proposed files. **If you have fewer than 15 files, go back and split more aggressively.**
+
+**Benefits:**
+- More scannable and maintainable
+- Easier to share specific subtrees with other agents
+- Natural progressive disclosure (load parent, then drill into children)
+- Works like a file system you're familiar with
+
+### Split Aggressively - Target 15-25 Files
 
-**Don't create monolithic blocks.** If a block is getting long (>50-100 lines), split it:
+**Don't create monolithic blocks.** Your goal is **15-25 total files**. Be aggressive about splitting:
 
-Instead of one huge `project` block, consider:
+**Split when:**
+- A block has **40+ lines** (lower threshold than typical)
+- A block has **2+ distinct concepts** (not 3+, be aggressive)
+- A section could stand alone as its own file
+- You can name the extracted content with a clear `/` path
+
+If a block is getting long (>40 lines), split it:
+
+**Without memory filesystem** (flat naming - acceptable but not ideal):
 - `project-overview`: High-level description, tech stack, repo links
 - `project-commands`: Build, test, lint, dev commands
 - `project-conventions`: Commit style, PR process, code style
 - `project-architecture`: Directory structure, key modules
 - `project-gotchas`: Footguns, things to watch out for
 
+**With memory filesystem** (MANDATORY hierarchical naming with `/`):
+- `project.md`: Index file listing all children
+- `project/overview`: High-level description, tech stack, repo links
+- `project/commands`: Build, test, lint, dev commands
+- `project/conventions`: Commit style, PR process, code style
+- `project/architecture`: Directory structure, key modules
+- `project/gotchas`: Footguns, things to watch out for
+- **Must further nest**: `project/tooling/testing`, `project/tooling/linting`, `project/tooling/bun`
+- **Target 15-25 files total** - if commands is long, split into `project/commands/dev`, `project/commands/build`, etc.
+
 This makes memory more scannable and easier to update and share with other agents.
 
 ### Update Memory Incrementally
@@ -290,33 +455,187 @@ And add memory blocks that you think make sense to add (e.g., `project-architect
 
 ## Your Task
 
-1. **Ask upfront questions**: Use AskUserQuestion with the recommended questions above (bundled together). This is critical - don't skip it.
-2. **Inspect existing memory**: You may already have some memory blocks initialized. See what already exists, and analyze how it is or is not insufficient or incomplete.
-3. **Identify the user**: From git logs and their answer, figure out who they are and store in `human` block. If relevant, ask questions to gather information about their preferences that will help you be a useful assistant to them.
-4. **Update human/persona early**: Based on answers, update your memory blocks eagerly before diving into project research. You can always change them as you go, you're not locked into any memory configuration.
-5. **Research the project**: Explore based on chosen depth. Use your TODO or plan tool to create a systematic research plan.
-6. **Create/update project blocks incrementally**: Don't wait until the end - write findings as you go.
-7. **Reflect and review**: See "Reflection Phase" below - this is critical for deep research.
-8. **Ask user if done**: Check if they're satisfied or want you to continue refining.
+1. **Check memory filesystem status**: Look for the `memory_filesystem` block to see if the filesystem feature is enabled. This determines whether you should organize memory hierarchically.
+
+2. **Ask upfront questions**: Use AskUserQuestion with the recommended questions above (bundled together). This is critical - don't skip it.
+
+3. **Inspect existing memory**: 
+   - If memfs enabled: Use `ls -la ~/.letta/agents/<agent-id>/memory/system/` to see the file structure
+   - Otherwise: Use memory tools to inspect existing blocks
+   - Analyze what exists and what needs improvement
+
+4. **Identify the user**: From git logs and their answer, figure out who they are and store in `human` block. If relevant, ask questions to gather information about their preferences that will help you be a useful assistant to them.
+
+5. **Update human/persona early**: Based on answers, update your memory blocks eagerly before diving into project research. You can always change them as you go, you're not locked into any memory configuration.
+
+6. **Research the project**: Explore based on chosen depth. Use your TODO or plan tool to create a systematic research plan.
+
+7. **Create/update memory structure**:
+   - **With memfs enabled**: Create a deeply hierarchical file structure using bash commands
+     - Use `mkdir -p` to create subdirectories (2-3 levels deep)
+     - Create `.md` files for memory blocks using `/` naming
+     - **Target 15-25 total files** - be aggressive about splitting
+     - Use nested paths like `project/tooling/testing.md` (never flat like `project-testing.md`)
+     - Create index files (`project.md`, `human.md`) with "Related blocks" sections
+     - **Every new file MUST be nested** under a parent using `/`
+   - **Without memfs**: Use memory tools to create/update blocks with hierarchical naming
+   - **Don't wait until the end** - write findings as you go
+   
+   **Checkpoint verification:**
+   - After creating files, count them: `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`
+   - **If count < 15, you haven't split enough** - go back and split more
+   - Check maximum depth: `find ~/.letta/agents/<agent-id>/memory/system/ -type f | awk -F/ '{print NF}' | sort -n | tail -1`
+   - **Should be 2-3 levels deep** minimum
+
+8. **Organize incrementally**:
+   - Start with a basic structure
+   - Add detail as you research
+   - Refine organization as patterns emerge
+   - Split large files into smaller, focused ones
+
+9. **Reflect and review**: See "Reflection Phase" below - this is critical for deep research.
+
+10. **Ask user if done**: Check if they're satisfied or want you to continue refining.
 
 ## Reflection Phase (Critical for Deep Research)
 
 Before finishing, you MUST do a reflection step. **Your memory blocks are visible to you in your system prompt right now.** Look at them carefully and ask yourself:
 
-1. **Redundancy check**: Are there blocks with overlapping content? Either literally overlapping (due to errors while making memory edits), or semantically/conceptually overlapping?
+1. **File count check**: 
+   - Count your memory files: `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`
+   - **Do you have 15-25 files?** If not, you haven't split enough
+   - Too few files means blocks are too large - split more aggressively
+
+2. **Hierarchy check**:
+   - Are ALL new files using `/` naming? (e.g., `project/tooling/bun.md`)
+   - Do you have 2-3 levels of nesting minimum?
+   - Are there any flat files like `project-commands.md`? **These should be nested**
+
+3. **Redundancy check**: Are there blocks with overlapping content? Either literally overlapping (due to errors while making memory edits), or semantically/conceptually overlapping?
 
-2. **Completeness check**: Did you actually update ALL relevant blocks? For example:
+4. **Completeness check**: Did you actually update ALL relevant blocks? For example:
    - Did you update `human` with the user's identity and preferences?
    - Did you update `persona` with behavioral rules they expressed?
    - Or did you only update project blocks and forget the rest?
 
-3. **Quality check**: Are there typos, formatting issues, or unclear descriptions in your blocks?
+5. **Quality check**: Are there typos, formatting issues, or unclear descriptions in your blocks?
 
-4. **Structure check**: Would this make sense to your future self? Is anything missing? Is anything redundant?
+6. **Structure check**: Would this make sense to your future self? Is anything missing? Is anything redundant?
 
 **After reflection**, fix any issues you found. Then ask the user:
 > "I've completed the initialization. Here's a brief summary of what I set up: [summary]. Should I continue refining, or is this good to proceed?"
 
 This gives the user a chance to provide feedback or ask for adjustments before you finish.
 
+## Working with Memory Filesystem (Practical Guide)
+
+If the memory filesystem feature is enabled, here's how to work with it during initialization:
+
+### Inspecting Current Structure
+
+```bash
+# See what memory files currently exist
+ls -la ~/.letta/agents/<agent-id>/memory/system/
+
+# Check the tree structure
+tree ~/.letta/agents/<agent-id>/memory/system/
+
+# Read existing memory files
+cat ~/.letta/agents/<agent-id>/memory/system/persona.md
+```
+
+### Creating Hierarchical Structure (MANDATORY)
+
+**Good examples (nested with `/`):**
+✅ `project/overview.md`
+✅ `project/tooling/bun.md`  
+✅ `project/tooling/testing.md`
+✅ `human/prefs/communication.md`
+✅ `persona/behavior/tone.md`
+
+**Bad examples (flat naming - NEVER do this):**
+❌ `project-overview.md` (flat, not nested)
+❌ `bun.md` (orphan file, no parent)
+❌ `project_testing.md` (underscore instead of `/`)
+
+```bash
+# Create deeply nested directory structure (2-3 levels)
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/project/{tooling,architecture,conventions}
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/human/prefs
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/persona/behavior
+
+# Create memory files using Write tool - ALL files must be nested
+Write({
+  file_path: "~/.letta/agents/<agent-id>/memory/system/project/overview.md",
+  content: "## Project Overview\n\n..."
+})
+
+Write({
+  file_path: "~/.letta/agents/<agent-id>/memory/system/project/tooling/testing.md",
+  content: "## Testing Setup\n\n..."
+})
+
+Write({
+  file_path: "~/.letta/agents/<agent-id>/memory/system/project/tooling/bun.md",
+  content: "## Bun Configuration\n\n..."
+})
+```
+
+### Organizing Existing Files
+
+```bash
+# If you have flat files that should be hierarchical
+mv ~/.letta/agents/<agent-id>/memory/system/project-tooling.md \
+   ~/.letta/agents/<agent-id>/memory/system/project/tooling.md
+
+# Create subdirectories as needed
+mkdir -p ~/.letta/agents/<agent-id>/memory/system/project/tooling
+mv ~/.letta/agents/<agent-id>/memory/system/project/tooling.md \
+   ~/.letta/agents/<agent-id>/memory/system/project/tooling/overview.md
+```
+
+### Creating Index Files
+
+Index files help navigate the hierarchy:
+
+```markdown
+# project.md (index file)
+
+## Project: [Project Name]
+
+This is the main project memory block. See specialized blocks for details:
+
+## Related blocks
+- `project/overview` - High-level description and tech stack
+- `project/commands` - Build, test, lint commands
+- `project/tooling` - Development tools index
+  - `project/tooling/testing` - Test framework details
+  - `project/tooling/linting` - Linter configuration
+- `project/architecture` - System design and structure
+- `project/gotchas` - Important warnings and footguns
+```
+
+### Final Checklist (Verify Before Submitting)
+
+Before you tell the user you're done, confirm:
+
+- [ ] **File count is 15-25** — Count your files with `ls ~/.letta/agents/<agent-id>/memory/system/ | wc -l`. If < 15, split more.
+- [ ] **All new files use `/` naming** — No flat files like `my_notes.md` or `project-commands.md`
+- [ ] **Hierarchy is 2-3 levels deep** — e.g., `project/tooling/bun.md`, not just `project.md`
+- [ ] **No file exceeds ~40 lines** — Split larger files
+- [ ] **Each file has one concept** — If 2+ topics, split into 2+ files
+- [ ] **Parent files have "Related blocks" sections** — Index files point to children
+- [ ] **Verify sync**: After creating files, check they appear in your memory blocks
+
+**If you have fewer than 15 files, you haven't split enough. Go back and split more.**
+
+### Best Practices
+
+1. **Check memfs status first**: Look for `memory_filesystem` block before deciding on organization strategy
+2. **Start with directories**: Create the directory structure before populating files
+3. **Use short paths**: Aim for 2-3 levels (e.g., `project/tooling/testing`, not `project/dev/tools/testing/setup`)
+4. **Keep files focused**: Each file should cover one concept (~40 lines max)
+5. **Create indexes**: Top-level files (`project.md`) should list children with "Related blocks"
+6. **Be aggressive about splitting**: If in doubt, split. Too many small files is better than too few large ones.
+
 Remember: Good memory management is an investment. The effort you put into organizing your memory now will pay dividends as you work with this user over time.

package/skills/syncing-memory-filesystem/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: syncing-memory-filesystem
+description: Manage memory filesystem sync conflicts with git-like commands. Load this skill when you receive a memFS conflict notification, need to check sync status, review diffs, or resolve conflicts between memory blocks and their filesystem counterparts.
+---
+
+# Memory Filesystem Sync
+
+When memFS is enabled, your memory blocks are mirrored as `.md` files on disk at `~/.letta/agents/<agent-id>/memory/`. Changes to blocks or files are detected via content hashing and synced at startup and on manual `/memfs-sync`.
+
+**Conflicts** occur when both the file and the block are modified since the last sync (e.g., user edits a file in their editor while the block is also updated manually by the user via the API). Non-conflicting changes (only one side changed) are resolved automatically during the next sync.
+
+## Scripts
+
+Three scripts provide a git-like interface for managing sync status:
+
+### 1. `memfs-status.ts` — Check sync status (like `git status`)
+
+```bash
+npx tsx <SKILL_DIR>/scripts/memfs-status.ts $LETTA_AGENT_ID
+```
+
+**Output**: JSON object with:
+- `conflicts` — blocks where both file and block changed (need manual resolution)
+- `pendingFromFile` — file changed, block didn't (resolved on next sync)
+- `pendingFromBlock` — block changed, file didn't (resolved on next sync)
+- `newFiles` — files without corresponding blocks
+- `newBlocks` — blocks without corresponding files
+- `isClean` — true if everything is in sync
+- `lastSync` — timestamp of last sync
+
+Read-only, safe to run anytime.
+
+### 2. `memfs-diff.ts` — View conflict details (like `git diff`)
+
+```bash
+npx tsx <SKILL_DIR>/scripts/memfs-diff.ts $LETTA_AGENT_ID
+```
+
+**Output**: Writes a formatted markdown diff file showing both the file version and block version of each conflicting label. The path to the diff file is printed to stdout.
+
+Use the `Read` tool to review the diff file content.
+
+### 3. `memfs-resolve.ts` — Resolve conflicts (like `git merge`)
+
+```bash
+npx tsx <SKILL_DIR>/scripts/memfs-resolve.ts $LETTA_AGENT_ID --resolutions '<JSON>'
+```
+
+**Arguments**:
+- `--resolutions` — JSON array of resolution objects
+
+**Resolution format**:
+```json
+[
+  {"label": "persona/soul", "resolution": "block"},
+  {"label": "human/prefs", "resolution": "file"}
+]
+```
+
+**Resolution options**:
+- `"file"` — Overwrite the memory block with the file contents
+- `"block"` — Overwrite the file with the memory block contents
+
+All resolutions must be provided in a single call (stateless).
+
+## Typical Workflow
+
+1. You receive a system reminder about memFS conflicts
+2. Run `memfs-diff.ts` to see the full content of both sides
+3. Read the diff file to understand the changes
+4. Decide for each conflict: keep the file version or the block version
+5. Run `memfs-resolve.ts` with all resolutions at once
+
+## Example
+
+```bash
+# Step 1: Check status (optional — the system reminder already tells you about conflicts)
+npx tsx <SKILL_DIR>/scripts/memfs-status.ts $LETTA_AGENT_ID
+
+# Step 2: View the diffs
+npx tsx <SKILL_DIR>/scripts/memfs-diff.ts $LETTA_AGENT_ID
+# Output: "Diff (2 conflicts) written to: /path/to/diff.md"
+
+# Step 3: Read the diff file (use Read tool on the path from step 2)
+
+# Step 4: Resolve all conflicts
+npx tsx <SKILL_DIR>/scripts/memfs-resolve.ts $LETTA_AGENT_ID --resolutions '[{"label":"persona/soul","resolution":"block"},{"label":"human/prefs","resolution":"file"}]'
+```
+
+## How Conflicts Arise
+
+- **User edits a `.md` file** in their editor or IDE while the corresponding block is also modified manually by the user via the API
+- **Both sides diverge** from the last-synced state — neither can be resolved automatically without potentially losing changes
+- The system detects this after each turn and notifies you via a system reminder
+
+## Notes
+
+- Non-conflicting changes (only one side modified) are resolved automatically during the next sync — you only need to intervene for true conflicts
+- The `/memfs-sync` command is still available for users to manually trigger sync and resolve conflicts via the CLI overlay
+- After resolving, the sync state is updated so the same conflicts won't reappear