@tznthou/ccrecall 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tznthou/ccrecall",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "AI memory service for Claude Code — on-demand context injection with metacognition",
   "type": "module",
   "main": "dist/index.js",
@@ -58,6 +58,7 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "lint": "eslint . --fix",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "eval:demo": "tsx evaluation/demo.ts"
   }
 }

package/scripts/extraction-prompt.md

@@ -21,13 +21,37 @@ NOT worth saving (noise):
 - Anything already stored in auto-memory or CLAUDE.md
 - Credentials, API keys, tokens, passwords
 
+## Lead with the prescription (most important rule)
+
+When this memory is injected into a future session, **only its first 149
+characters survive** — the rest is truncated away. The reader sees the opening
+and nothing else, and has to decide what to do from that alone.
+
+So open with the thing a future reader should DO. Put the evidence, the war
+story and the file names after it.
+
+- BAD — the actionable half never arrives:
+  "Three file-cut attempts failed (M8 missing quote, M18 punctuation style, M20
+  paragraph detection) before realizing the patterns were wrong, not the data
+  missing. Mitigation: pre-verify patterns by running grep first."
+- GOOD — survives the cut intact:
+  "Pre-verify a grep pattern against the live file (confirm >= 1 hit) before
+  encoding it into an assertion: zero-hits reads the same whether the pattern is
+  wrong or the data is absent. Hit three times — M8, M18, M20."
+
+This is not a length limit. Write the full memory; just order it so the first
+sentence carries the instruction rather than the narrative that produced it.
+
+If a memory has no action attached — a pure fact, a decision record, a version
+quirk — lead with the conclusion instead. Never lead with the investigation.
+
 ## How to write each memory
 
 Every memory must be **self-contained** — a future reader in a different project
 has zero context about this session.
 
 Rules:
-1. Include the WHY, not just the WHAT
+1. Include the WHY, not just the WHAT — but after the prescription, not before it
 2. Use concrete details: file paths (relative, not absolute), command names,
    version numbers, error messages
 3. Replace pronouns ("we", "it", "this") with specific nouns
@@ -72,6 +96,26 @@ memory is updated instead of duplicated. Choose keys that are:
 - Stable enough that the same insight would get the same key next time
 - Lowercase, hyphenated, no special characters
 
+## Message provenance (messageId)
+
+Every turn in the transcript is headed `--- human [<uuid>] ---` or
+`--- assistant [<uuid>] ---`. That uuid identifies the message.
+
+For each memory, pass the uuid of the ONE message that most directly produced
+it — where the decision was stated, the root cause named, the preference
+expressed. Copy it verbatim out of the header.
+
+- **Never invent, reconstruct, or guess a uuid.** If no single message stands
+  out, omit `messageId` entirely. A missing citation costs nothing; a wrong one
+  makes a memory look sourced when it is not, which is worse than unsourced.
+- A header printed without a uuid (`--- human ---`) cannot be cited. Omit.
+- Citing a message is **not** a claim that the message proves the memory. It
+  records where you drew it from, so a human can go read that turn later. Pick
+  the most direct source; do not stretch to manufacture one.
+- The save path checks the uuid against this session's real messages. One it
+  cannot find is dropped, the memory is saved without it, and the result says
+  so. Do not retry — the turn budget is better spent on saves not yet made.
+
 ## recall_save parameters
 
 For each memory, call `recall_save` with:
@@ -82,6 +126,13 @@ For each memory, call `recall_save` with:
 - `projectId`: include for project-specific, omit for cross-project
 - `sessionId`: the Origin session ID given in the transcript header above —
   pass it verbatim so each memory can be traced back to its origin session
+- `messageId`: the uuid of the single message this memory came from, copied
+  from its `--- human [<uuid>] ---` header (see above). Omit when no one
+  message is the source — never guess one
+- `origin`: always `"agent-inferred"`. You are reading a finished transcript
+  with nobody watching, so your saves must not overwrite a memory the user
+  wrote by hand under the same key. Omitting this marks your save as the
+  user's own and removes that protection.
 
 ## Output