fix(prompt): write memories in Claude Code's current frontmatter format

[kuitos]

Problem

#47: memories the main agent wrote did not match Claude Code's current format.

	before	Claude Code 2.1.289
name:	a title (No autouse pytest fixtures)	a kebab-case slug, normally the file name
type:	top level	under metadata:
file name	snake_case	kebab-case

In the report, all 12 files the main agent wrote used the old shape. The prompts taught it:

• FRONTMATTER_EXAMPLE (name: {{memory name}}, top-level type:);
• the user_role.md / feedback_testing.md examples;
• name: short title and snake_case file names in the extraction prompt;
• "Human-readable name" and "Use snake_case" in memory_save's args;
• the README example.

A memory folder shared with Claude Code ended up holding two formats.

Fix

• Every prompt, the memory_save arg descriptions and the README now show the current format: a kebab-case slug name, metadata:\n type:, and kebab-case file names. The examples are user-role.md and no-db-mocks-in-tests.md.
• name is not forced to equal the file name; real Claude Code files differ.
• A slug makes a poor index title, so memory_save gains an optional title for the MEMORY.md line, defaulting to name. It names a new line or a line the plugin generated, never a hand-written one (fix(store): keep hand-written MEMORY.md index lines #51).
• The main-agent prompt says memory_save does both steps (file and index line), so the agent should not edit MEMORY.md itself afterwards. If it ever edits the index by hand, it changes one line and never rewrites the file. See the verification below for why.
• Old files are read as before and are not migrated.
• AGENTS.md notes the format.

Tests

• test/prompt.test.ts:
  • main and extraction prompts teach the slug and metadata.type, and the old shapes are gone;
  • the main agent leaves MEMORY.md to memory_save.
• test/store/MemoryStore.test.ts:
  • a title names a new index line while the file keeps the slug;
  • a titled generated line follows a new description;
  • a title retitles a line generated from the name;
  • a title never replaces a hand-written line.
• test/tools.test.ts: memory_save writes a slug name and metadata.type and titles the index line with title, falling back to name.
• bun run lint, bun run typecheck, bun test and bun run build pass.

Real-environment verification (OpenCode 2.0.22, isolated DB/config, memory agents on opencode/gpt-6-luna)

Format: in the extraction and fact-statement scenarios (the ones that create memories), every new memory file used a kebab-case slug name and metadata.type, 20/20. That covers extraction forks and memory_save calls from big-pickle and gpt-6-luna main agents. Forks passed a readable title (e.g. [Billing database](billing-postgres.md)).

Main agent editing MEMORY.md itself (big-pickle, after memory_save had already written the index line):

• Before the "do not edit MEMORY.md yourself" sentence, 3 of the 6 inspected runs:
  • one overwrote the whole file with write, dropping a hand-written line;
  • one edit appended a duplicate line;
  • one more edit touched the index.
• After it: 0/3, with the hand-written line kept each time.
• Small sample, and the model's own file tools remain outside the plugin's control.

Refs #47

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 2.1.3 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀