Skip to content

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

Rust

fix(mcp): steer write_page toward H1-in-body title convention

AkitaOnRailscbda9695abd8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index faa21be2..37fc0780 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
before removal ([#55]).
### Fixed
+- `memory_write_page` tool description and routing prompts now steer agents
+ toward writing the page title as a `# H1` on the first line of `body` and
+ omitting the `title` argument. ai-memory already auto-derived the title from
+ `# H1` (or path stem) when `title` was missing — the change is documentation
+ only, but it eliminates a known source of MCP `JSON parsing` errors when the
+ LLM failed to escape quotes/colons in `title` ([#67]).
- Custom `--web-ui-dir` frontends no longer serve raw `/index.html` without
base-path injection; direct index requests and SPA fallback routes now return
the injected shell, while static assets remain untouched ([#65]).
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index e604539b..d4688dbc 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -69,7 +69,7 @@ match the intent to the tool. They do not need to name the tool.
| "where did we leave off?" — and no such block is visible | `memory_handoff_accept` (rare; the SessionStart hook usually got there first) |
| "save context for the next session" / wrapping up | `memory_handoff_begin` (single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets) |
| "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |
-| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes) |
+| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) |
| "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) |
| "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent) |
| "audit the wiki" / "find contradictions" / "what rules should we add?" | `memory_lint` |
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 78914b2b..56e51840 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -78,7 +78,10 @@ the conversation calls for them:\n\
session end only when AI_MEMORY_CONSOLIDATE_ON_SESSION_END is set.\n\
- `memory_write_page` — when the user explicitly asks to remember, \
save, or annotate durable project knowledge. This writes a wiki page; \
- do NOT use `memory_handoff_begin` for permanent annotations.\n\
+ do NOT use `memory_handoff_begin` for permanent annotations. \
+ Put the title as a `# H1` on the first line of `body` and omit the \
+ `title` argument — ai-memory derives the title automatically and \
+ passing `title` is a known JSON-escape footgun (issue #67).\n\
- `memory_read_page` — when the user asks to read, open, or show the \
full content of a specific page. Accepts a `query` (searches FTS5 and \
returns the top hit's full body) or a `path` (direct lookup). Pass \
@@ -409,9 +412,18 @@ struct DeletePageArgs {
struct WritePageArgs {
/// Relative wiki path to write, for example `notes/santander-2025.md`.
path: String,
- /// Markdown body. Pass the durable fact/note content, not a handoff summary.
+ /// Markdown body. Pass the durable fact/note content, not a handoff
+ /// summary. Start the body with `# Some Title` — ai-memory derives the
+ /// page title from that H1 automatically, so you do not need (and should
+ /// not pass) the `title` argument.
body: String,
- /// Optional page title; otherwise derived from the first H1 or path stem.
+ /// **Prefer omitting this.** ai-memory derives the title from the first
+ /// `# H1` in `body` (or the path stem if there is no heading), so the
+ /// safest call is to leave this out and put the title as a markdown H1
+ /// on the first line of `body`. Passing a title here forces the agent
+ /// to JSON-escape the string correctly — a known source of `JSON parsing`
+ /// errors when the title contains quotes, colons, or other punctuation
+ /// (issue #67). Only set this when there's no usable H1 in the body.
#[serde(default)]
title: Option<String>,
/// Tier (`working`, `episodic`, `semantic`, `procedural`). Default semantic.
@@ -983,7 +995,14 @@ impl AiMemoryServer {
memory_handoff_begin for permanent annotations. Choose a stable \
relative path such as `notes/<topic>.md`, `concepts/<topic>.md`, \
`decisions/<topic>.md`, or `_rules/<topic>.md`. `tier` defaults \
- to `semantic`; set `pinned=true` for facts that should never decay.")]
+ to `semantic`; set `pinned=true` for facts that should never decay. \
+ \
+ **Title convention:** start `body` with a `# Some Title` line — \
+ ai-memory derives the title from that H1 automatically. Do NOT \
+ pass the `title` argument; passing it forces correct JSON-escaping \
+ of the string and is a known source of `JSON parsing` errors when \
+ the title contains quotes or punctuation (issue #67). Use `title` \
+ only when there's no usable H1 in the body.")]
async fn memory_write_page(
&self,
Parameters(args): Parameters<WritePageArgs>,
@@ -1754,6 +1773,25 @@ mod tests {
}
}
+ /// Both prompt surfaces must steer agents toward the H1-in-body
+ /// convention instead of passing the `title` argument. The `title`
+ /// argument is a known source of `JSON parsing` errors when the LLM
+ /// fails to escape quotes (issue #67); routing every "remember this"
+ /// call through the H1 path avoids the footgun entirely.
+ #[test]
+ fn prompts_steer_write_page_toward_h1_title_convention() {
+ for prompt in [MEMORY_INSTRUCTIONS, ai_memory_core::SNIPPET_BODY] {
+ assert!(
+ prompt.contains("H1"),
+ "prompt must mention the H1 title convention for memory_write_page"
+ );
+ assert!(
+ prompt.contains("omit") || prompt.contains("Omit"),
+ "prompt must tell the agent to omit the `title` argument"
+ );
+ }
+ }
+
/// Read tools resolve the project in the order: explicit `project`
/// arg in the active workspace, explicit `project` in the baked
/// workspace, hook-published active project, baked-in default (issue #2).