Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(memory): teach installed clients anchored patches

AkitaOnRailsc185f2a94580
diff --git a/crates/ai-memory-core/src/routing_skills.rs b/crates/ai-memory-core/src/routing_skills.rs
index 84012b38..148c96bf 100644
--- a/crates/ai-memory-core/src/routing_skills.rs
+++ b/crates/ai-memory-core/src/routing_skills.rs
@@ -145,6 +145,7 @@ mod tests {
("memory_message_pop", "ai-memory-messaging"),
("memory_message_cancel", "ai-memory-messaging"),
("memory_write_page", "ai-memory-durable-pages"),
+ ("memory_patch_page", "ai-memory-durable-pages"),
("memory_delete_page", "ai-memory-durable-pages"),
("memory_restore_page", "ai-memory-durable-pages"),
("memory_consolidate", "ai-memory-learning-maintenance"),
diff --git a/crates/ai-memory-core/src/routing_skills/ai-memory-durable-pages/SKILL.md b/crates/ai-memory-core/src/routing_skills/ai-memory-durable-pages/SKILL.md
index a5c2c460..8ccf8ccd 100644
--- a/crates/ai-memory-core/src/routing_skills/ai-memory-durable-pages/SKILL.md
+++ b/crates/ai-memory-core/src/routing_skills/ai-memory-durable-pages/SKILL.md
@@ -10,7 +10,9 @@ Use this skill only for deliberate durable wiki mutations. Routine session captu
## Tools in this cluster
-- `memory_write_page` writes a durable wiki page for permanent project knowledge.
+- `memory_write_page` writes or replaces a durable wiki page for permanent project knowledge.
+- `memory_patch_page` atomically changes named Markdown sections in an existing
+ page without re-emitting its frontmatter or unrelated body.
- `memory_delete_page` removes a durable wiki page by exact path.
- `memory_restore_page` lists a page's checkpoints (no `rev`) or writes an
earlier version back (with `rev`), including a deleted page. It is admin
@@ -30,9 +32,20 @@ target arrays, 32 targets total, 1,024 characters each). Relation targets use
resolve with `.md`, and scope components must already be trimmed. Limits apply
to raw values before trimming, normalization or deduplication. Arbitrary
frontmatter and author fields are not editable.
-Every write replaces the whole page and its metadata; omitted fields are
-cleared. Read the current page first when preserving existing content matters.
-There is no patch or compare-and-write precondition.
+Every `memory_write_page` call replaces the whole page and its metadata;
+omitted fields are cleared. Read the current page first when preserving
+existing content matters, and pass its returned `page_id` as
+`expected_page_id` so a concurrent change fails without writing. Use
+`create_only: true` when the page must not already exist; do not combine the
+two preconditions.
+
+For a targeted edit, prefer `memory_patch_page`: read the page, pass its
+required `page_id` as `expected_page_id`, and submit one bounded batch.
+`append_to_section` and `add_section` use heading anchors from the read
+response; `replace_section` must also carry that section's returned `sha256`.
+All edits resolve against the same captured body and either commit together or
+write nothing. Missing, duplicate, stale, or conflicting anchors fail closed.
+Use `memory_write_page` when replacing the whole document.
When the user explicitly wants a note to be temporary, pass `expires_at` as an
RFC3339 instant or a bare `YYYY-MM-DD` (the end of that day in UTC). After the
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index c79f45d1..4209b5df 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -1728,11 +1728,15 @@ struct PatchPageArgs {
expected_page_id: String,
/// Anchored edits, all resolved against the same captured base body.
edits: Vec<crate::page_patch::PagePatchEdit>,
- /// Project containing the existing page. Static clients pass this with
- /// `workspace`; partial explicit scope fails closed.
+ /// Project containing the existing page. Session-aware clients may omit it
+ /// for the current project. Static MCP clients must pass it together with
+ /// `workspace` for every project-scoped call; partial explicit scope fails
+ /// closed.
#[serde(default)]
project: Option<String>,
/// Workspace containing the existing page, together with `project`.
+ /// Session-aware clients may omit both for the current project; static MCP
+ /// clients must pass both.
#[serde(default)]
workspace: Option<String>,
}
diff --git a/plugins/claude-code/skills/ai-memory-durable-pages/SKILL.md b/plugins/claude-code/skills/ai-memory-durable-pages/SKILL.md
index a5c2c460..8ccf8ccd 100644
--- a/plugins/claude-code/skills/ai-memory-durable-pages/SKILL.md
+++ b/plugins/claude-code/skills/ai-memory-durable-pages/SKILL.md
@@ -10,7 +10,9 @@ Use this skill only for deliberate durable wiki mutations. Routine session captu
## Tools in this cluster
-- `memory_write_page` writes a durable wiki page for permanent project knowledge.
+- `memory_write_page` writes or replaces a durable wiki page for permanent project knowledge.
+- `memory_patch_page` atomically changes named Markdown sections in an existing
+ page without re-emitting its frontmatter or unrelated body.
- `memory_delete_page` removes a durable wiki page by exact path.
- `memory_restore_page` lists a page's checkpoints (no `rev`) or writes an
earlier version back (with `rev`), including a deleted page. It is admin
@@ -30,9 +32,20 @@ target arrays, 32 targets total, 1,024 characters each). Relation targets use
resolve with `.md`, and scope components must already be trimmed. Limits apply
to raw values before trimming, normalization or deduplication. Arbitrary
frontmatter and author fields are not editable.
-Every write replaces the whole page and its metadata; omitted fields are
-cleared. Read the current page first when preserving existing content matters.
-There is no patch or compare-and-write precondition.
+Every `memory_write_page` call replaces the whole page and its metadata;
+omitted fields are cleared. Read the current page first when preserving
+existing content matters, and pass its returned `page_id` as
+`expected_page_id` so a concurrent change fails without writing. Use
+`create_only: true` when the page must not already exist; do not combine the
+two preconditions.
+
+For a targeted edit, prefer `memory_patch_page`: read the page, pass its
+required `page_id` as `expected_page_id`, and submit one bounded batch.
+`append_to_section` and `add_section` use heading anchors from the read
+response; `replace_section` must also carry that section's returned `sha256`.
+All edits resolve against the same captured body and either commit together or
+write nothing. Missing, duplicate, stale, or conflicting anchors fail closed.
+Use `memory_write_page` when replacing the whole document.
When the user explicitly wants a note to be temporary, pass `expires_at` as an
RFC3339 instant or a bare `YYYY-MM-DD` (the end of that day in UTC). After the
diff --git a/plugins/codex/skills/ai-memory-durable-pages/SKILL.md b/plugins/codex/skills/ai-memory-durable-pages/SKILL.md
index a5c2c460..8ccf8ccd 100644
--- a/plugins/codex/skills/ai-memory-durable-pages/SKILL.md
+++ b/plugins/codex/skills/ai-memory-durable-pages/SKILL.md
@@ -10,7 +10,9 @@ Use this skill only for deliberate durable wiki mutations. Routine session captu
## Tools in this cluster
-- `memory_write_page` writes a durable wiki page for permanent project knowledge.
+- `memory_write_page` writes or replaces a durable wiki page for permanent project knowledge.
+- `memory_patch_page` atomically changes named Markdown sections in an existing
+ page without re-emitting its frontmatter or unrelated body.
- `memory_delete_page` removes a durable wiki page by exact path.
- `memory_restore_page` lists a page's checkpoints (no `rev`) or writes an
earlier version back (with `rev`), including a deleted page. It is admin
@@ -30,9 +32,20 @@ target arrays, 32 targets total, 1,024 characters each). Relation targets use
resolve with `.md`, and scope components must already be trimmed. Limits apply
to raw values before trimming, normalization or deduplication. Arbitrary
frontmatter and author fields are not editable.
-Every write replaces the whole page and its metadata; omitted fields are
-cleared. Read the current page first when preserving existing content matters.
-There is no patch or compare-and-write precondition.
+Every `memory_write_page` call replaces the whole page and its metadata;
+omitted fields are cleared. Read the current page first when preserving
+existing content matters, and pass its returned `page_id` as
+`expected_page_id` so a concurrent change fails without writing. Use
+`create_only: true` when the page must not already exist; do not combine the
+two preconditions.
+
+For a targeted edit, prefer `memory_patch_page`: read the page, pass its
+required `page_id` as `expected_page_id`, and submit one bounded batch.
+`append_to_section` and `add_section` use heading anchors from the read
+response; `replace_section` must also carry that section's returned `sha256`.
+All edits resolve against the same captured body and either commit together or
+write nothing. Missing, duplicate, stale, or conflicting anchors fail closed.
+Use `memory_write_page` when replacing the whole document.
When the user explicitly wants a note to be temporary, pass `expires_at` as an
RFC3339 instant or a bare `YYYY-MM-DD` (the end of that day in UTC). After the