gh-arittr-tabula-scripta/commands/update-memory.md

Update Memory - Update Existing Note

Update an existing memory note with new information, using patch operations and conflict detection.

Usage

/update-memory [title]

Arguments:

• title - The title of the existing memory note to update (required)

Examples:

/update-memory Git Worktrees
/update-memory 2025-11-18 - Working Memory Implementation
/update-memory React Patterns

Implementation

When this command is invoked:

1. Parse and Validate Title

1. Parse the title by trimming whitespace from the command input
2. Validate that the title is not empty
   • If title is empty, return error message: "Title is required. Usage: /update-memory [title]"

2. Detect Project Context

1. Attempt to detect the current project from the git repository:
   • Run git rev-parse --show-toplevel to find the git repository root
   • Extract the project name from the repository directory name
2. If not in a git repository:
   • Fall back to using the current working directory name
   • If that fails, use 'default' as the project name
3. Store the detected project name for locating the note

3. Search for Note

1. Try to find the note by checking multiple possible locations in order:

   • Current project entities: claude/projects/{currentProject}/entities/{title}.md
   • Current project sessions: claude/projects/{currentProject}/sessions/{title}.md
   • Global entities: claude/global/entities/{title}.md
   • Global topics: claude/global/topics/{title}.md

2. For each possible path:

   • Attempt to read the note using MCP read_note
   • If successful, store the path and note content, then stop searching
   • If FileNotFoundError, continue to next path
   • If other error, propagate it

3. If not found in standard locations, use search as fallback:

   • Invoke MCP search_notes with query=title and path_filter='claude/**'
   • Find exact title match in results (case-insensitive comparison)
   • If exact match found, load the note using MCP read_note

4. If still not found after all attempts:

   • Return error message listing all searched locations
   • Suggest using /remember to create the note
   • Provide example command

4. Load Note and Check Timestamps

1. Store the loaded timestamp from frontmatter for conflict detection later

   • Save note.frontmatter.updated as the loaded timestamp

2. Update claude_last_accessed in frontmatter to current date (YYYY-MM-DD)

3. Display the current note content to the user:

   • Show wikilink title, type, project, last updated date, and path
   • Display full current content
   • Add separator line
   • Prompt: "What would you like to update? I'll apply patch operations to preserve existing content."

5. Collect User Updates

This is a conversational step where the user describes what they want to update.

1. User provides their update request in natural language

   • Example: "Add a new decision about using trap handlers for cleanup"

2. Parse the user's intent to identify the appropriate patch operation type:

   • Append to section: Add new entry to an existing section (e.g., "## Recent Changes")
   • Add new section: Create a completely new section (e.g., "## Troubleshooting")
   • Update frontmatter: Modify frontmatter fields (e.g., add a tag)
   • Insert in list: Add item to an existing list (e.g., "## Related Entities")

3. Confirm with the user what will be done

   • Example: "I'll add this to the Key Decisions section."

6. Check for Conflicts (Before Writing)

Use the conflict detection logic defined in the managing-working-memory skill:

1. Before applying the patch, reload the note using MCP read_note to get the current state

2. Compare timestamps to detect conflicts:

   • Get the current timestamp from the reloaded note's frontmatter.updated
   • Compare with the loaded timestamp saved in step 4
   • If current timestamp > loaded timestamp: CONFLICT DETECTED (human edited since Claude loaded)
   • If timestamps match: No conflict, safe to update

3. If conflict detected:

   • Trigger conflict resolution flow (see managing-working-memory skill for detailed flow)
   • Present both changes to user and offer resolution options

4. If no conflict:

   • Proceed to apply patch operation in next step

7. Apply Patch Operation

Use the patch operation patterns defined in the managing-working-memory skill. Apply the identified patch operation type:

For append_to_section:

• Locate the specified section in the note content
• Append the new content to the end of that section
• Preserve all existing content in the section

For add_new_section:

• Create a new markdown section with the specified title
• Add the section content
• Insert at appropriate location in the note structure

For update_frontmatter:

• Modify the specified frontmatter field(s)
• Common operations: adding tags, updating status, etc.

For insert_in_list:

• Locate the specified list within a section
• Add the new list item
• Maintain proper markdown list formatting

After applying content changes:

1. Update frontmatter timestamps:

   • Set updated to current date (YYYY-MM-DD)
   • Set claude_last_accessed to current date (YYYY-MM-DD)

2. If adding tags, merge new tags with existing tags (remove duplicates)

8. Write Updated Note

1. Invoke MCP update_note with:

   • vault: ~/.claude-memory
   • path: The note path
   • content: The updated content
   • frontmatter: The updated frontmatter

2. Handle the response:

   If successful:

   • Return success message including:
     • Confirmation with wikilink
     • Description of applied changes
     • Updated timestamp
     • Path
     • Note that Obsidian has been updated

   If MCPUnavailableError:

   • Return graceful degradation message explaining:
     • MCP server is unavailable
     • Steps to restore: ensure Obsidian is running, check plugin installation, verify config
     • Reference to docs/setup-guide.md
     • Offer to save pending update to a local file

   If other error:

   • Return error message with details

Conflict Detection and Resolution

All conflict detection and resolution flows are defined in the managing-working-memory skill. The /update-memory command uses these patterns:

Case 1: Clean Update (No Conflict)

Timeline:

• T1: Claude loads note (updated = "2025-11-17")
• T2: User discusses updates with Claude
• T3: Claude applies patch (updated still "2025-11-17")
• Result: No conflict, proceed with update

See managing-working-memory skill for timestamp comparison logic.

Example Output:

Updated: [[Git Worktrees]]

Applied changes:
- Added new entry to "Recent Changes"
- Appended decision about trap handlers to "Key Decisions"
- Updated tags: [entity, git, worktrees, error-handling]

Updated: 2025-11-18
Path: claude/projects/tabula-scripta/entities/Git Worktrees.md

The note has been updated in Obsidian.

Case 2: Human Edit Conflict

Timeline:

• T1: Claude loads note (updated = "2025-11-17")
• T2: Human edits note in Obsidian (updated = "2025-11-18")
• T3: Claude attempts patch (detects conflict)
• Result: Conflict detected, show diff and offer resolution options

See managing-working-memory skill for conflict resolution flow and user options.

Example Output:

I want to update [[Git Worktrees]] but you've edited it since I loaded it.

Your changes (at 2025-11-18):
  + Added new section "## Performance Considerations"
  + Updated "Overview" with additional context
  ~ Modified frontmatter tags: added #optimization

My pending changes:
  - Add new entry to "Recent Changes"
  - Append decision about trap handlers to "Key Decisions"

Options:
1. Show me both diffs and I'll merge manually
2. Abort your update (keep my changes only)
3. Create new section "## Claude's Updates (conflicted)" with your changes
4. Let's discuss and resolve together

What should I do?

Case 3: Major Rewrite Needed

When Claude's understanding contradicts existing note fundamentally, use the major rewrite pattern from managing-working-memory skill to present options without overwriting user knowledge.

Example Output:

My understanding of [[Git Worktrees]] changed significantly.

Current note says:
"Git worktrees are primarily for parallel feature development and should be short-lived."

But I now think:
"Git worktrees can be long-lived for maintaining multiple release branches simultaneously."

Options:
1. Create new entity note with alternative understanding
2. Update existing note (I'll show you the full diff first)
3. Let's discuss the contradiction - maybe both are valid

What should I do?

Patch Operation Types

All patch operations are defined in the managing-working-memory skill. The /update-memory command uses these standard patterns:

1. Append to Section

Add new content at the end of an existing section. Example: Adding to "## Recent Changes" section.

See managing-working-memory skill for appendToSection pattern.

2. Add New Section

Create a new section in the note. Example: Adding "## Performance Considerations" section.

See managing-working-memory skill for addSection pattern.

3. Update Frontmatter

Modify frontmatter fields such as tags or status.

Examples:

• Adding a tag: Append to tags array
• Changing status: Set status field to new value

See managing-working-memory skill for frontmatter update pattern.

4. Insert in List

Add item to an existing list like "## Related Entities" or "## References".

See managing-working-memory skill for insertInList pattern.

Error Handling

Note Not Found

Input: /update-memory Nonexistent Entity

Output:

Error: Memory note [[Nonexistent Entity]] not found.

Searched:
- Project entities: claude/projects/tabula-scripta/entities/
- Project sessions: claude/projects/tabula-scripta/sessions/
- Global entities: claude/global/entities/
- Global topics: claude/global/topics/

Would you like to create it with /remember?

Example: /remember entity Nonexistent Entity

MCP Unavailable

Input: /update-memory Git Worktrees (when MCP server is down)

Output:

Obsidian MCP server is unavailable. Cannot update memory note.

To restore memory features:
1. Ensure Obsidian is running
2. Check obsidian-mcp-plugin is installed in ~/.claude-memory/
3. Verify Claude Code config includes MCP server

See docs/setup-guide.md for troubleshooting.

Would you like me to save the pending update to a local file?

Missing Title

Input: /update-memory

Output:

Error: Title is required.

Usage: /update-memory [title]

Examples:
  /update-memory Git Worktrees
  /update-memory 2025-11-18 - Working Memory Implementation
  /update-memory React Patterns

Success Output (Clean Update)

Input: /update-memory Git Worktrees

Conversation:

User: /update-memory Git Worktrees

Claude: Loaded: [[Git Worktrees]]
Type: entity
Project: tabula-scripta
Last updated: 2025-11-17
Path: claude/projects/tabula-scripta/entities/Git Worktrees.md

Current content:
[... full note content ...]

---

What would you like to update? I'll apply patch operations to preserve existing content.

User: Add a decision about using trap handlers for cleanup

Claude: I'll add this to the Key Decisions section.

[Claude applies patch]

Updated: [[Git Worktrees]]

Applied changes:
- Added new entry to "Key Decisions"
  ### Trap Handlers for Cleanup
  Date: 2025-11-18
  Rationale: Ensures worktree cleanup even if subagent crashes
  Alternatives Considered: Manual cleanup (error-prone), atexit hooks (unreliable)
  Impact: Improves reliability of parallel execution

Updated: 2025-11-18
Path: claude/projects/tabula-scripta/entities/Git Worktrees.md

The note has been updated in Obsidian.

Timestamp Tracking

Frontmatter Fields

---
created: 2025-11-17      # Never changes, original creation
updated: 2025-11-18      # Modified every save (human or Claude)
claude_last_accessed: 2025-11-18  # When Claude loaded into context
---

Conflict Detection Logic

See the managing-working-memory skill for the complete timestamp comparison logic. The basic flow is:

1. When loading: Store the updated timestamp and set claude_last_accessed
2. When updating: Reload the note and compare timestamps
3. If current timestamp > loaded timestamp: Conflict detected
4. If timestamps match: Safe to update

Graceful Degradation (MCP Unavailable)

When MCP server is unavailable:

1. Detect failure - Catch MCPUnavailableError
2. Offer alternatives:
   • Save pending update to local markdown file
   • Export as diff patch for manual application
   • Continue conversation without update
3. Guide troubleshooting:
   • Link to docs/setup-guide.md
   • Check Obsidian is running
   • Verify plugin installation

Interactive Update Flow

The /update-memory command is conversational:

1. Load note - Show current content to user
2. Collect intent - User describes what to update
3. Confirm operation - Claude describes patch operation
4. Check conflict - Reload note to detect edits
5. Apply or resolve - Update cleanly or trigger conflict resolution
6. Confirm success - Show what changed

This ensures transparency and prevents data loss.

Acceptance Criteria

• Loads existing note via MCP read_note
• Checks timestamps for conflict detection (updated vs loaded)
• Detects conflicts when human edited since load
• Shows diff when conflict detected
• Applies patch operations (append, add section, update frontmatter)
• Preserves existing content (no full rewrites)
• Updates frontmatter timestamps (updated, claude_last_accessed)
• Handles MCP unavailable gracefully
• Offers to create note if not found
• Searches multiple locations (project entities, sessions, global)
• Shows clear success message with changes applied

Integration with managing-working-memory Skill

This command provides the manual interface for memory updates. The managing-working-memory skill uses the same update logic for:

• Automatic updates after code review
• Updates after debugging sessions
• Periodic checkpoint updates
• Session end compaction

Relationship:

• /update-memory - Manual, user-initiated updates
• managing-working-memory - Automatic, skill-driven updates
• Both use identical conflict detection and patch operations
• Both track timestamps for data integrity