hippocamp 0.2.0 → 0.2.2

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.0",
+  "version": "0.2.2",
   "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.",
       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)}`;
 
@@ -924,8 +926,22 @@ 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.
+  for (const hit of index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE })) {
+    const added = blocks[hit.id].length + (picked.length ? 2 : 0);
+
+    if (length + added > SEARCH_EXCERPT_MAX_CHARS) {
+      continue;
+    }
+
+    picked.push(hit.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 +992,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 +1047,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({

package/scripts/install-claude.cjs

@@ -116,7 +116,6 @@ function buildClaudeManagedBlock() {
     "- Do not duplicate commits, PRs, issues, reviews, or CI results in memory; store references plus the missing rationale, preference, assumption, or follow-up context.",
     "- If a project-memory write does not sync automatically, call `sync_memory` before finishing the task.",
     "- If the user asks to upgrade Hippocamp for Claude Code, run `npx hippocamp@latest upgrade-claude`; from a source checkout, run `git pull --ff-only`, `npm install`, then `npm run upgrade:claude`.",
-    "- Before writing, reviewing, or refactoring code, read and follow `/Users/guillaumegay/.agents/skills/karpathy-guidelines/SKILL.md` unless the user explicitly asks to skip it.",
     CLAUDE_MANAGED_END,
     "",
   ].join("\n");

package/test/memory-efficiency.test.cjs

@@ -221,3 +221,128 @@ 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);
+});

package/test/package-paths.test.cjs

@@ -0,0 +1,30 @@
+const assert = require("node:assert/strict");
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+test("published files contain no local home directory paths", () => {
+  const root = path.join(__dirname, "..");
+  // npm is npm.cmd on Windows, which Node only runs through a shell.
+  const output = execFileSync("npm", ["pack", "--dry-run", "--json"], {
+    cwd: root,
+    encoding: "utf8",
+    shell: process.platform === "win32",
+  });
+  const [pack] = JSON.parse(output);
+  const textFiles = pack.files.map((file) => file.path).filter((file) => !file.endsWith(".png"));
+  const matches = [];
+
+  for (const file of textFiles) {
+    const content = fs.readFileSync(path.join(root, file), "utf8");
+
+    for (const [index, line] of content.split("\n").entries()) {
+      if (/\/Users\/[A-Za-z0-9._-]+|\/home\/[A-Za-z0-9._-]+/.test(line)) {
+        matches.push(`${file}:${index + 1}`);
+      }
+    }
+  }
+
+  assert.deepEqual(matches, []);
+});