Maintain the memory

This journey keeps the folder in good shape: spot defects (a broken link, an orphan note, an unreadable frontmatter…), repair them, and tidy up (rename, move, merge, remove) without breaking links. The application can do part of it alone; the agent takes the rest.

What you ask the agent

You ask your agent

« Run a health check of the memory. »

→ The agent callsmem_health_scan

You ask your agent

« Show me what the automatic repair would fix, without writing anything. »

→ The agent callsmem_health_repair

You ask your agent

« Apply that repair. »

→ The agent callsmem_health_repair

• apply = true
• plan_id = 3f9a1c0e

You ask your agent

« Which health tasks fall to me? The summaries to compose, first. »

→ The agent callsmem_health_tasks

• kind = compose-summary

You ask your agent

« Rename the kessho-docs project to kessho-documentation, and update the links that point at it across the whole vault. »

→ The agent callsmem_rename

• old_slug = kessho-docs
• new_slug = kessho-documentation
• rewrite_links = true

You ask your agent

« Show me what moving 20-knowledge/runner.md to 20-knowledge/architecture/runner.md would do. »

→ The agent callsmem_move

• path = 20-knowledge/runner.md
• to = 20-knowledge/architecture/runner.md

You ask your agent

« Apply that move. »

→ The agent callsmem_move

• path = 20-knowledge/runner.md
• to = 20-knowledge/architecture/runner.md
• apply = true

You ask your agent

« Undo the last move. »

→ The agent callsmem_move_undo

You ask your agent

« Remove the note 20-knowledge/note-de-test.md: it duplicates runner.md. »

→ The agent callsmem_remove

• path = 20-knowledge/note-de-test.md
• confirm = true
• reason = Duplicate of runner.md.

You ask your agent

« On second thought, put that note back. »

→ The agent callsmem_restore

• path = 20-knowledge/note-de-test.md

What the agent does

Check, then repair

1. mem_health_scan audits the vault. Read-only, in all circumstances. category restricts the audit to one category (the list is in the reference). Each finding says who can repair it: stage is app (the automatic repair step), agent (a task for the agent) or none (with the reason).
2. mem_health_repair applies the fixes whose answer is unique and safe. By default it is a dry run: the answer carries a plan_id, the number of fixes and the files concerned, and nothing is written. With apply: true, the agent must hand back that plan_id: without it, or if the memory changed since, nothing is written. No other parameter is accepted (dry_run is refused), and nothing is ever deleted.
3. mem_health_tasks lists what calls for judgment: a summary to compose, an orphan note to attach, a link with no safe target, a merge conflict, a moved repository. kind filters by kind, limit (30 by default) and cursor paginate. Each task names the tools to use and its end criterion: the finding disappears from the scan. The agent handles each task, then reruns mem_health_scan to check.

Tidy up

These tools also rewrite the links that point to what they move (wikilinks, Markdown links, frontmatter), across the whole vault. rewrite_links: false turns that rewriting off for mem_rename, mem_merge and mem_reclass.

• mem_move renames or moves a file or folder. Without apply, it returns the plan and writes nothing: files moved, each link before and after, links left, warnings, empreinte (the plan's fingerprint). With apply: true, it applies; if empreinte is given and the vault changed since, nothing is written. It refuses an occupied target, an invalid name, a protected folder, a git operation in progress, or a plan that would break a link.
• mem_rename renames a project or domain (old_slug, new_slug); mem_merge merges two projects or two domains of the same kind (source_slug, deleted after the merge, into target_slug); mem_reclass changes a note's scope (scope) or zone (zone). These three tools write as soon as they are called: they have no dry run. To go back, see mem_move_undo below.
• mem_move_undo undoes the vault's last move operation (mem_move, mem_rename, mem_reclass, mem_merge, or the same gesture made in the application): files and links return to their previous state. It refuses if a touched file has changed since.

Remove

mem_remove moves a note to the vault's trash (.trash/), with an attached note (date, reason, former path); it never deletes. Its guards:

• a note created by this server during the current session can be removed freely; for any other, confirm: true and a non-empty reason are required;
• a note cited by others is refused, with the list of citing notes; force: true removes it anyway and returns every link that became dangling;
• it refuses index.md, context.md, history.md, .obsidian/ and .trash/, and any removal while a git operation is in progress;
• it writes an audit line in 99-meta/migrations/removals.md. A note already pushed stays in git history.

mem_restore puts it back, byte for byte, and refuses if a file already occupies its original path: nothing is ever overwritten.

Other tidying tools exist, for example mem_attach (attach an orphan note to a project or a domain) or mem_accept_dangling (declare a deliberate dead link); they are in the MCP reference.

What you see

• Health. The status bar shows the memory's HEALTH, and the home screen carries the Memory Health Score. It counts the anomalies and separates what the application repairs alone from what falls to an agent ("N tasks for an agent", with Copy the instruction). Prepare the repair follows the same two-step principle as mem_health_repair: a plan, then Apply; an outdated plan is refused. See Home.
• Tidy up and remove. In a zone, a note's menu offers Rename, Move and Remove, with a preview of the links to update and an Undo button to go back; Remove sends the note to the trash (.trash) and offers Remove anyway when other notes cite it. See Zones.
• What the agent has just changed. The freshness indicator lights up after every agent write and names the zone touched; Reload refreshes the screen (see Zones).