hippocamp 0.2.1 → 0.2.3

package/.github/workflows/ci.yml

@@ -23,3 +23,4 @@ jobs:
       - run: node --check scripts/*.cjs
       - run: npm run mcp:help
       - run: npm run mcp:smoke
+      - run: npm test

package/AGENTS.md

@@ -26,6 +26,7 @@ This repository is a local-first MCP package for Git-backed agent memory. Keep c
 - `scripts/hippocamp-dream.cjs`: offline Dream CLI for scheduled compaction of curated project wake-up files.
 - `scripts/hippocamp-memory.cjs`: local filesystem-backed Hippocamp memory helpers for MCP use.
 - `scripts/hippocamp-mcp.cjs`: local stdio MCP server for Hippocamp memory tools.
+- `scripts/eval-lagoon.cjs`: read-only retrieval check against real Lagoon cases in `<Lagoon root>/evals/retrieval-cases.json`.
 - `scripts/eval-retrieval.cjs`: retrieval-only LongMemEval-S check for `searchMemory` against a BM25 reference.
 - `scripts/install-claude.cjs`: one-step installer for Claude Code MCP setup and user-level `CLAUDE.md` guidance.
 - `scripts/install-codex.cjs`: one-step installer for the Hippocamp skill and MCP server in Codex.
@@ -72,7 +73,7 @@ When changing code, use the smallest verification that proves the change:
 - Run `npm run mcp:help` when changing MCP registration or commands.
 - Run `npm run mcp:smoke` when changing memory reads, root resolution, or wake-up behavior.
 - Run `npm run dream -- --help` when changing Dream CLI arguments.
-- Run `npm run eval:retrieval -- --limit 100` when changing search ranking or snippets; report Recall@5 against the BM25 row.
+- Run `npm run eval:retrieval -- --limit 100` when changing search ranking or snippets; report Recall@5 against the BM25 row and snippet evidence. Also run `npm run eval:lagoon` when a Lagoon is available.
 
 ## Notes For Future Agents
 

package/README.md

@@ -252,6 +252,7 @@ npm run mcp:help
 npm run mcp:smoke
 npm run dream
 npm run dream:railway
+npm run eval:lagoon
 npm run eval:retrieval
 npm run install:codex
 npm run install:claude
@@ -261,7 +262,9 @@ npm run upgrade:claude
 npm run upgrade:grok
 ```
 
-`npm run eval:retrieval` measures search on LongMemEval-S without any model: Recall@5, Hit@5, MRR, returned context size, and latency, next to an in-process BM25 reference. Run it with `--help` for the one-time data download.
+`npm run eval:retrieval` measures search on LongMemEval-S without any model: Recall@5, Hit@5, MRR, snippet evidence (the returned text comes from an answer turn), returned context size, and latency, next to an in-process BM25 reference. Run it with `--help` for the one-time data download.
+
+`npm run eval:lagoon` runs the same kind of check, read-only, against your real Lagoon. It reads cases from `<Lagoon root>/evals/retrieval-cases.json`: a project, a query, and the event ids that answer it. An empty list means no memory should be returned. Keep the cases in Lagoon, not in this repo, because they quote private work.
 
 ## Releases
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippocamp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "description": "Local Git-backed memory for AI agents.",
   "license": "MIT",
@@ -30,6 +30,7 @@
   "scripts": {
     "dream": "node scripts/hippocamp-dream.cjs",
     "dream:railway": "bash assets/railway/run-dream.sh",
+    "eval:lagoon": "node scripts/eval-lagoon.cjs",
     "eval:retrieval": "node scripts/eval-retrieval.cjs",
     "install:claude": "node scripts/install-claude.cjs",
     "install:codex": "node scripts/install-codex.cjs",

package/scripts/eval-lagoon.cjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+const fsSync = require("node:fs");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const memory = require("./hippocamp-memory.cjs");
+
+const MAX_TOP_K = 20;
+const DEFAULT_CASES = "evals/retrieval-cases.json";
+
+function printHelp() {
+  console.log(`Hippocamp Lagoon eval
+
+Read-only retrieval check against your real Lagoon. No model or API key is used.
+Each case names a project, a query, and the event ids that answer it.
+An empty expect list means no memory should be returned.
+
+Usage:
+  npm run eval:lagoon -- [--cases PATH] [--top-k K]
+
+Options:
+  --cases PATH  Cases JSON. Default: <Lagoon root>/${DEFAULT_CASES}
+  --top-k K     Results retrieved per query, at most ${MAX_TOP_K}. Default: 5
+  --help        Show this help
+
+Cases file:
+  { "cases": [ { "project": "<slug>", "query": "...", "expect": ["<event id>"] } ] }
+`);
+}
+
+function parseArgs(argv) {
+  const options = { cases: path.join(memory.getGlobalRoot(), DEFAULT_CASES), topK: 5, help: false };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+    } else if (token === "--cases") {
+      options.cases = argv[++index];
+    } else if (token === "--top-k") {
+      const number = Number(argv[++index]);
+
+      if (!Number.isInteger(number) || number < 1 || number > MAX_TOP_K) {
+        throw new Error(`--top-k must be an integer from 1 to ${MAX_TOP_K}.`);
+      }
+
+      options.topK = number;
+    } else {
+      throw new Error(`Unknown argument: ${token}`);
+    }
+  }
+
+  return options;
+}
+
+async function run(options) {
+  if (!fsSync.existsSync(options.cases)) {
+    throw new Error(`Missing ${options.cases}. Run with --help for the file format.`);
+  }
+
+  const { cases } = JSON.parse(await fs.readFile(options.cases, "utf8"));
+  // searchMemory derives the project slug from the folder name, so a bare temp
+  // folder per slug reads that project's memory without touching any real repo.
+  const sandboxRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-eval-lagoon-"));
+  const answerable = { count: 0, hit: 0, mrr: 0, chars: 0, topScores: [] };
+  const empty = { count: 0, correct: 0, topScores: [] };
+
+  try {
+    for (const item of cases) {
+      if (!/^[a-z0-9][a-z0-9._-]*$/.test(String(item.project))) {
+        throw new Error(`Invalid project slug: ${item.project}`);
+      }
+
+      const projectRoot = path.join(sandboxRoot, item.project);
+      await fs.mkdir(projectRoot, { recursive: true });
+
+      const search = await memory.searchMemory({
+        query: item.query,
+        scope: "project",
+        projectRoot,
+        maxResults: options.topK,
+      });
+      const topScore = search.results[0]?.score ?? 0;
+
+      if (!item.expect.length) {
+        empty.count += 1;
+        empty.correct += search.results.length ? 0 : 1;
+        empty.topScores.push(topScore);
+        console.log(`${search.results.length ? "MISS" : "ok  "}  empty   top ${topScore}  [${item.project}] ${item.query}`);
+        continue;
+      }
+
+      const rank = search.results.findIndex((result) => item.expect.includes(result.id));
+      answerable.count += 1;
+      answerable.hit += rank === -1 ? 0 : 1;
+      answerable.mrr += rank === -1 ? 0 : 1 / (rank + 1);
+      answerable.chars += search.results.reduce((sum, result) => sum + result.snippet.length, 0);
+      answerable.topScores.push(topScore);
+      console.log(
+        `${rank === -1 ? "MISS" : "ok  "}  rank ${rank === -1 ? "-" : rank + 1}  top ${topScore}  [${item.project}] ${item.query}`,
+      );
+    }
+  } finally {
+    await fs.rm(sandboxRoot, { recursive: true, force: true });
+  }
+
+  const percent = (part, whole) => `${((part / Math.max(whole, 1)) * 100).toFixed(1)}%`;
+  const range = (scores) => (scores.length ? `${Math.min(...scores)}-${Math.max(...scores)}` : "n/a");
+
+  console.log(`\nLagoon retrieval, K=${options.topK}, ${cases.length} cases`);
+  console.log(
+    `answerable (${answerable.count})  Hit@K ${percent(answerable.hit, answerable.count)}  MRR ${(answerable.mrr / Math.max(answerable.count, 1)).toFixed(3)}  context ${Math.round(answerable.chars / Math.max(answerable.count, 1))} chars  top score ${range(answerable.topScores)}`,
+  );
+  console.log(
+    `no memory  (${empty.count})  empty result ${percent(empty.correct, empty.count)}  top score ${range(empty.topScores)}`,
+  );
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  await run(options);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/scripts/eval-retrieval.cjs

@@ -132,6 +132,19 @@ function rankBm25(query, documents) {
     .map((item) => item.document);
 }
 
+// Words too common to show that a question and its evidence share wording.
+const STOPWORDS = new Set(
+  "about after also been before could does from have into just many much over some such than that their them then there these they this what when where which while with would your".split(" "),
+);
+
+function contentTokens(value) {
+  return new Set(tokenize(value).filter((token) => token.length > 3 && !STOPWORDS.has(token)));
+}
+
+function squashSpace(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
 function retrievalMetrics(retrievedIds, answerIds) {
   const expected = new Set(answerIds);
   const hits = retrievedIds.filter((id) => expected.has(id)).length;
@@ -145,10 +158,10 @@ function retrievalMetrics(retrievedIds, answerIds) {
 }
 
 function addMetrics(bucket, system, metrics) {
-  const total = (bucket[system] ||= { recall: 0, hit: 0, mrr: 0, contextChars: 0, latencyMs: 0, count: 0 });
+  const total = (bucket[system] ||= { recall: 0, hit: 0, mrr: 0, evidence: 0, contextChars: 0, latencyMs: 0, count: 0 });
 
-  for (const key of ["recall", "hit", "mrr", "contextChars", "latencyMs"]) {
-    total[key] += metrics[key];
+  for (const key of ["recall", "hit", "mrr", "evidence", "contextChars", "latencyMs"]) {
+    total[key] += metrics[key] ?? Number.NaN;
   }
 
   total.count += 1;
@@ -162,6 +175,7 @@ function formatRow(label, total) {
     `Recall@K ${(average("recall") * 100).toFixed(1)}%`,
     `Hit@K ${(average("hit") * 100).toFixed(1)}%`,
     `MRR ${average("mrr").toFixed(3)}`,
+    Number.isNaN(total.evidence) ? "evidence  n/a " : `evidence ${(average("evidence") * 100).toFixed(1)}%`,
     `context ${Math.round(average("contextChars"))} chars`,
     `latency ${average("latencyMs").toFixed(0)} ms`,
   ].join("  ");
@@ -181,6 +195,8 @@ async function run(options) {
   const previousGlobalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
   const overall = {};
   const byType = {};
+  const misses = [];
+  let withEvidenceTurns = 0;
 
   process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(sandboxRoot, "lagoon");
 
@@ -201,6 +217,12 @@ async function run(options) {
       }
 
       const answerIds = item.answer_session_ids.map(String);
+      const evidenceTurns = item.haystack_sessions
+        .filter((_, index) => answerIds.includes(String(item.haystack_session_ids[index])))
+        .flat()
+        .filter((turn) => turn.has_answer)
+        .map((turn) => squashSpace(turn.content));
+      withEvidenceTurns += evidenceTurns.length ? 1 : 0;
       let startedAt = performance.now();
       const search = await memory.searchMemory({
         query: item.question,
@@ -212,14 +234,31 @@ async function run(options) {
         ...retrievalMetrics(search.results.map((result) => pathToSessionId.get(result.path)), answerIds),
         latencyMs: performance.now() - startedAt,
         contextChars: search.results.reduce((sum, result) => sum + result.snippet.length, 0),
+        // The snippet itself comes from a turn marked has_answer, not only the right session.
+        evidence: search.results.some((result) =>
+          result.snippet
+            .split(/\n\s*\n/)
+            .map(squashSpace)
+            .some((part) => evidenceTurns.some((turn) => turn.includes(part) || part.includes(turn))),
+        )
+          ? 1
+          : 0,
       };
 
+      if (!hippocamp.hit && evidenceTurns.length) {
+        const shared = [...contentTokens(item.question)].filter((token) =>
+          evidenceTurns.some((turn) => contentTokens(turn).has(token)),
+        );
+        misses.push({ type: item.question_type, sharedWords: shared.length });
+      }
+
       startedAt = performance.now();
       const bm25Documents = rankBm25(item.question, documents).slice(0, options.topK);
       const bm25 = {
         ...retrievalMetrics(bm25Documents.map((document) => document.sessionId), answerIds),
         latencyMs: performance.now() - startedAt,
         contextChars: bm25Documents.reduce((sum, document) => sum + document.content.length, 0),
+        evidence: null,
       };
 
       for (const bucket of [overall, (byType[item.question_type] ||= {})]) {
@@ -250,6 +289,14 @@ async function run(options) {
     console.log(formatRow(system, total));
   }
 
+  const noSharedWords = misses.filter((miss) => miss.sharedWords === 0).length;
+  console.log(
+    `\nevidence: a hippocamp snippet is text from a has_answer turn (${withEvidenceTurns} questions have such turns).`,
+  );
+  console.log(
+    `wording: ${misses.length} hippocamp misses (Hit@K 0); ${noSharedWords} share no content word with the answer turns.`,
+  );
+
   for (const [type, systems] of Object.entries(byType)) {
     console.log(`\n${type} (${systems.bm25.count})`);
 

package/scripts/hippocamp-mcp.cjs

@@ -162,7 +162,7 @@ async function main() {
     "search_memory",
     {
       description:
-        "Search task-specific memory. Event search uses cue indexes and returns only bounded coherent evidence; it does not scan unindexed event logs as a fallback.",
+        "Search task-specific memory. Event search uses cue indexes and returns only bounded coherent evidence; it does not scan unindexed event logs as a fallback. Event results carry their ISO timestamp as id; use it for when-questions. A month name in the query favors events from that month. A YYYY-MM-DD date, today, yesterday, this/last week, or this/last month keeps only events from those dates (UTC); undated files still match.",
       inputSchema: {
         query: z.string(),
         scope: z.enum(["global", "project", "both"]).default("both"),

package/scripts/hippocamp-memory.cjs

@@ -28,6 +28,8 @@ const SEARCH_FIELD_BOOST = { cues: 3, heading: 2 };
 const SEARCH_FUZZY_DISTANCE = 0.2;
 const SEARCH_INDEX_CACHE_LIMIT = 8;
 const SEARCH_EXCERPT_MAX_CHARS = 1200;
+const EVENT_LOCK_RETRY_MS = 10;
+const EVENT_LOCK_STALE_MS = 10_000;
 const searchIndexCache = new Map();
 const PROCESS_SESSION_ID = `mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
 
@@ -745,6 +747,7 @@ function createQueryInfo(query) {
     normalized: tokens.join(" "),
     cue: tokens.join("-"),
     tokens,
+    datePrefixes: queryDatePrefixes(original),
   };
 }
 
@@ -893,7 +896,7 @@ function splitOversizedBlock(block) {
   return chunks;
 }
 
-function createSearchExcerpt(content, queryInfo) {
+function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
   const trimmed = content.trim();
 
   if (!trimmed) {
@@ -924,8 +927,25 @@ function createSearchExcerpt(content, queryInfo) {
 
   index.addAll(blocks.map((text, position) => ({ position, text })));
 
-  const [best] = index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE });
-  return best ? blocks[best.id] : null;
+  const picked = [];
+  let length = 0;
+
+  // Keep the best-matching paragraphs that fit the excerpt budget, in file order.
+  const hits = index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE }).map((hit) => hit.id);
+
+  // An event chosen by its date may share no words with the query; then lead with its first paragraphs.
+  for (const id of hits.length || !leadWhenUnmatched ? hits : blocks.map((_, position) => position)) {
+    const added = blocks[id].length + (picked.length ? 2 : 0);
+
+    if (length + added > SEARCH_EXCERPT_MAX_CHARS) {
+      continue;
+    }
+
+    picked.push(id);
+    length += added;
+  }
+
+  return picked.length ? picked.sort((left, right) => left - right).map((id) => blocks[id]).join("\n\n") : null;
 }
 
 async function readMemoryFile({ scope, path: relativePath, projectRoot }) {
@@ -976,6 +996,39 @@ async function writeMemoryFile({ scope, path: relativePath, content, projectRoot
   };
 }
 
+// Serialize read-modify-write of one event file across processes. The lock lives
+// in the temp directory so a crashed writer never leaves it in the Lagoon repo.
+async function withEventFileLock(filePath, action) {
+  const lockName = crypto.createHash("sha1").update(filePath).digest("hex");
+  const lockPath = path.join(os.tmpdir(), `hippocamp-event-${lockName}.lock`);
+
+  for (;;) {
+    try {
+      await (await fs.open(lockPath, "wx")).close();
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+
+      const stats = await statIfExists(lockPath);
+
+      if (stats && Date.now() - stats.mtimeMs > EVENT_LOCK_STALE_MS) {
+        await fs.rm(lockPath, { force: true });
+        continue;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, EVENT_LOCK_RETRY_MS));
+    }
+  }
+
+  try {
+    return await action();
+  } finally {
+    await fs.rm(lockPath, { force: true });
+  }
+}
+
 async function appendEvent({
   scope = "project",
   content,
@@ -998,18 +1051,30 @@ async function appendEvent({
       : body.trim();
   const attributionSection = formatAttributionSection(attribution);
   const eventBody = attributionSection ? `${attributionSection}\n\n${cuedBody}` : cuedBody;
-  const heading = title ? `## ${timestamp} — ${title.trim()}` : `## ${timestamp}`;
-  const eventBlock = `${heading}\n\n${eventBody}\n`;
   const relativePath = `events/${date}.md`;
   const target = resolveScopedPath(scope, relativePath, projectRoot);
-  const existing = await readFileIfExists(target.absolutePath);
-  const nextContent = existing?.trim()
-    ? `${existing.trimEnd()}\n\n${eventBlock.trimEnd()}\n`
-    : `# Events — ${date}\n\n${eventBlock.trimEnd()}\n`;
 
   await ensureParentDirectory(target.absolutePath);
-  await fs.writeFile(target.absolutePath, nextContent, "utf8");
-  const indexPath = await writeEventIndex(target.absolutePath, target.path);
+
+  const { eventBlock, indexPath } = await withEventFileLock(target.absolutePath, async () => {
+    const existing = await readFileIfExists(target.absolutePath);
+    const takenIds = new Set(parseEventBlocks(existing || "").map((event) => event.id));
+
+    // The timestamp is the event id, and search matches index entries to blocks by id.
+    while (takenIds.has(timestamp) && !Number.isNaN(Date.parse(timestamp))) {
+      timestamp = new Date(Date.parse(timestamp) + 1).toISOString();
+    }
+
+    const heading = title ? `## ${timestamp} — ${title.trim()}` : `## ${timestamp}`;
+    const block = `${heading}\n\n${eventBody}\n`;
+    const nextContent = existing?.trim()
+      ? `${existing.trimEnd()}\n\n${block.trimEnd()}\n`
+      : `# Events — ${date}\n\n${block.trimEnd()}\n`;
+
+    await fs.writeFile(target.absolutePath, nextContent, "utf8");
+
+    return { eventBlock: block, indexPath: await writeEventIndex(target.absolutePath, target.path) };
+  });
 
   const syncResult = sync
     ? await syncMemory({
@@ -1153,9 +1218,47 @@ async function collectMarkdownDocuments({ scope, root, curatedFiles }) {
   };
 }
 
+const MONTH_NAMES = "january february march april may june july august september october november december".split(" ");
+
+// Search word for a UTC day ("2026-08-05" -> "d20260805") or month ("2026-08" -> "august").
+// A day is one exact word, so it never matches a neighbor day by typo tolerance.
+function dateTerm(prefix) {
+  return prefix.length === 10 ? `d${prefix.replace(/-/g, "")}` : MONTH_NAMES[Number(prefix.slice(5, 7)) - 1];
+}
+
+// Month and day words of an event's timestamp id.
+function eventDateText(id) {
+  return /^\d{4}-\d{2}-\d{2}T/.test(id || "") ? `${dateTerm(id.slice(0, 7))} ${dateTerm(id.slice(0, 10))}` : "";
+}
+
+// Dates a query asks for: YYYY-MM-DD dates and relative phrases, as UTC day
+// ("2026-08-05") or month ("2026-08") prefixes of event ids. Weeks start on Monday.
+function queryDatePrefixes(query, now = new Date()) {
+  const text = query.toLowerCase();
+  const prefixes = [...text.matchAll(/\b\d{4}-\d{2}-\d{2}\b/g)].map((match) => match[0]);
+  const utc = (months, days) =>
+    new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + months, days)).toISOString();
+  const addDays = (from, to) => {
+    for (let offset = from; offset <= to; offset += 1) {
+      prefixes.push(utc(0, now.getUTCDate() + offset).slice(0, 10));
+    }
+  };
+  const addMonth = (offset) => prefixes.push(utc(offset, 1).slice(0, 7));
+  const monday = -((now.getUTCDay() + 6) % 7);
+
+  if (/\btoday\b/.test(text)) addDays(0, 0);
+  if (/\byesterday\b/.test(text)) addDays(-1, -1);
+  if (/\bthis week\b/.test(text)) addDays(monday, 0);
+  if (/\blast week\b/.test(text)) addDays(monday - 7, monday - 1);
+  if (/\bthis month\b/.test(text)) addMonth(0);
+  if (/\blast month\b/.test(text)) addMonth(-1);
+
+  return prefixes;
+}
+
 function buildSearchIndex(documents) {
   const index = new MiniSearch({
-    fields: ["cues", "heading", "body"],
+    fields: ["cues", "heading", "body", "date"],
     idField: "position",
     tokenize: tokenizeSearchText,
     processTerm: (term) => term,
@@ -1167,6 +1270,7 @@ function buildSearchIndex(documents) {
       cues: (document.cues || []).join(" "),
       heading: document.heading || document.path,
       body: document.body,
+      date: eventDateText(document.id),
     })),
   );
 
@@ -1174,10 +1278,16 @@ function buildSearchIndex(documents) {
 }
 
 function rankSearchDocuments(queryInfo, { index, documents }) {
+  const { datePrefixes } = queryInfo;
+
+  // A date the query asks for filters events to those dates. Undated files always pass.
   return index
-    .search(queryInfo.normalized, {
+    .search([queryInfo.normalized, ...datePrefixes.map(dateTerm)].join(" "), {
       boost: SEARCH_FIELD_BOOST,
-      fuzzy: SEARCH_FUZZY_DISTANCE,
+      fuzzy: (term) => (/^d\d{8}$/.test(term) ? 0 : SEARCH_FUZZY_DISTANCE),
+      filter: datePrefixes.length
+        ? (hit) => !documents[hit.id].id || datePrefixes.some((prefix) => documents[hit.id].id.startsWith(prefix))
+        : undefined,
     })
     .slice(0, SEARCH_CANDIDATE_LIMIT)
     .map((hit) => ({
@@ -1187,7 +1297,7 @@ function rankSearchDocuments(queryInfo, { index, documents }) {
 }
 
 function toSearchResult(queryInfo, { document, score }) {
-  const snippet = createSearchExcerpt(document.body, queryInfo);
+  const snippet = createSearchExcerpt(document.body, queryInfo, queryInfo.datePrefixes.length > 0);
 
   if (!snippet) {
     return null;

package/test/memory-efficiency.test.cjs

@@ -221,3 +221,245 @@ test("search returns whole sentences from an oversized matching paragraph", asyn
   assert.ok(search.results[0].snippet.length <= 1200);
   assert.match(search.results[0].snippet, /^The weekly sync|^The kestrel/);
 });
+
+test("search returns every matching paragraph that fits the excerpt budget", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-multi-paragraph-"));
+  const projectRoot = path.join(tempRoot, "multi-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const filler = "The weekly sync covered routine updates.";
+  const paragraphs = [
+    "The kestrel move started on Monday.",
+    ...Array(30).fill(filler),
+    "The kestrel database move finished in eu-west-3 on Friday.",
+  ];
+  await memory.appendEvent({
+    content: paragraphs.join("\n\n"),
+    cues: ["infra"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    title: "Weekly sync",
+  });
+
+  const search = await memory.searchMemory({ projectRoot, query: "kestrel database move", scope: "project" });
+  const snippet = search.results[0].snippet;
+
+  // The last paragraph matches more query words, so only the file-order sort puts it second.
+  assert.ok(snippet.indexOf("started on Monday") < snippet.indexOf("finished in eu-west-3"));
+  assert.match(snippet, /The kestrel move started on Monday\./);
+  assert.match(snippet, /The kestrel database move finished in eu-west-3/);
+  assert.ok(snippet.length <= 1200);
+});
+
+test("events appended in the same millisecond keep distinct ids and bodies", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-same-ms-"));
+  const projectRoot = path.join(tempRoot, "same-ms-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const timestamp = "2026-10-01T09:00:00.000Z";
+  const first = await memory.appendEvent({
+    content: "The zanzibar migration needs a rollback plan.",
+    cues: ["deploy"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    timestamp,
+    title: "Deploy note",
+  });
+  const second = await memory.appendEvent({
+    content: "Invoices are generated monthly.",
+    cues: ["billing"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    timestamp,
+    title: "Billing note",
+  });
+
+  assert.equal(first.timestamp, timestamp);
+  assert.equal(second.timestamp, "2026-10-01T09:00:00.001Z");
+
+  const search = await memory.searchMemory({ projectRoot, query: "invoices monthly", scope: "project" });
+
+  assert.equal(search.results.length, 1);
+  assert.equal(search.results[0].heading, "Billing note");
+  assert.match(search.results[0].snippet, /Invoices are generated monthly\./);
+});
+
+test("parallel appends keep every event", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-parallel-append-"));
+  const projectRoot = path.join(tempRoot, "parallel-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const results = await Promise.all(
+    Array.from({ length: 20 }, (_, index) =>
+      memory.appendEvent({
+        content: `Parallel event ${index}.`,
+        cues: ["parallel"],
+        date: "2026-10-01",
+        projectRoot,
+        scope: "project",
+        sync: false,
+        timestamp: "2026-10-01T09:00:00.000Z",
+        title: `Event ${index}`,
+      }),
+    ),
+  );
+  const content = await fs.readFile(results[0].root + "/events/2026-10-01.md", "utf8");
+  const ids = [...content.matchAll(/^## (\S+)/gm)].map((match) => match[1]);
+
+  assert.equal(ids.length, 20);
+  assert.equal(new Set(ids).size, 20);
+  assert.equal(new Set(results.map((result) => result.timestamp)).size, 20);
+});
+
+test("search favors events from a month named in the query", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-month-search-"));
+  const projectRoot = path.join(tempRoot, "month-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  for (const timestamp of ["2026-05-02T08:00:00.000Z", "2026-08-05T10:00:00.000Z", "2026-09-01T09:00:00.000Z"]) {
+    await memory.appendEvent({
+      content: "Published the Android build to Google Play production.",
+      cues: ["android-release"],
+      date: timestamp.slice(0, 10),
+      projectRoot,
+      scope: "project",
+      sync: false,
+      timestamp,
+      title: "Android release",
+    });
+  }
+
+  const byMonth = await memory.searchMemory({ projectRoot, query: "android build in august", scope: "project" });
+  const byDay = await memory.searchMemory({ projectRoot, query: "android build 2026-05-02", scope: "project" });
+
+  assert.equal(byMonth.results[0].id, "2026-08-05T10:00:00.000Z");
+  assert.equal(byDay.results[0].id, "2026-05-02T08:00:00.000Z");
+});
+
+test("search favors events from a relative date named in the query", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-relative-date-"));
+  const projectRoot = path.join(tempRoot, "relative-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  // Seven days ago is always in last calendar week; one day ago is yesterday.
+  const daysAgo = (days) => new Date(Date.now() - days * 86_400_000).toISOString();
+  const timestamps = { yesterday: daysAgo(1), lastWeek: daysAgo(7), older: daysAgo(30) };
+
+  for (const [key, timestamp] of Object.entries(timestamps)) {
+    await memory.appendEvent({
+      // The old event matches the words better, so only the date words can rank the others first.
+      content: key === "older" ? "Deploy key rotation: rotated the deploy key again." : "Rotated the key for staging.",
+      cues: ["deploy-key"],
+      date: timestamp.slice(0, 10),
+      projectRoot,
+      scope: "project",
+      sync: false,
+      timestamp,
+      title: "Deploy key rotation",
+    });
+  }
+
+  const ids = async (phrase) =>
+    (await memory.searchMemory({ projectRoot, query: `deploy key rotation ${phrase}`, scope: "project" })).results.map(
+      (result) => result.id,
+    );
+
+  assert.deepEqual(await ids("yesterday"), [timestamps.yesterday]);
+  // On a Monday, yesterday is also in last week.
+  const lastWeek = await ids("last week");
+  assert.ok(lastWeek.includes(timestamps.lastWeek));
+  assert.ok(!lastWeek.includes(timestamps.older));
+  assert.deepEqual(await ids("today"), []);
+});
+
+test("search returns a snippet for a long event matched only by its date", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-date-only-"));
+  const projectRoot = path.join(tempRoot, "date-only-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await memory.appendEvent({
+    content: Array(30).fill("The weekly sync covered routine updates.").join("\n\n"),
+    cues: ["sync"],
+    date: "2026-08-05",
+    projectRoot,
+    scope: "project",
+    sync: false,
+    timestamp: "2026-08-05T10:00:00.000Z",
+    title: "Weekly sync",
+  });
+
+  const search = await memory.searchMemory({ projectRoot, query: "2026-08-05", scope: "project" });
+
+  assert.equal(search.results.length, 1);
+  assert.match(search.results[0].snippet, /^The weekly sync covered routine updates\./);
+  assert.ok(search.results[0].snippet.length <= 1200);
+});