hippocamp 0.2.10 → 0.2.12

package/AGENTS.md

@@ -48,7 +48,7 @@ This repository is a local-first MCP package for Git-backed agent memory. Keep c
 - Global memory lives under `HIPPOCAMP_GLOBAL_ROOT/`.
 - Project memory lives under `HIPPOCAMP_GLOBAL_ROOT/projects/<slug>/`.
 - The current project slug is inferred from `HIPPOCAMP_PROJECT_ROOT` or the current working directory. An existing folder with nothing but `.git` has no project; project scope then resolves to the global root.
-- Event logs are append-only daily Markdown files under `events/YYYY-MM-DD.md`, with sibling `events/YYYY-MM-DD.index.json` keyword indexes.
+- Event logs are append-only daily Markdown files under `events/YYYY-MM-DD.md`, with sibling `events/YYYY-MM-DD.index.json` keyword indexes. The one exception is the installer's keyword-link format upgrade of older events.
 - Curated files such as `current_state.md` and `open_threads.md` use explicit file writes.
 - MCP `append_event` requires a title and 1-8 keywords; MCP `write_memory_file` rejects paths under `events/`; an explicit `projectRoot` must be a directory inside a Git repository.
 - `append_event` auto-stamps `Agent:` / `Session:` provenance when resolvable (installer env, MCP client name, or process session id). No manual user config.
@@ -85,4 +85,4 @@ When changing code, use the smallest verification that proves the change:
 - The cloud/API version is intentionally deferred.
 - Do not reintroduce Next.js, GitHub API token auth, or GitHub App auth for the local MVP.
 - Keep Dream minimal: scheduled updates and coherent compaction, two curated files plus bounded indexed evidence, one PR per project.
-- The local install story should stay: `npx hippocamp@latest install`, a local Lagoon repo created if missing, normal Git auth. Installers never create remotes or push.
+- The local install story should stay: `npx hippocamp@latest install`, a local Lagoon repo created if missing, normal Git auth. Installers never create remotes or push; their only event rewrite is one local keyword-link format upgrade of older events, the exception to the append-only event invariant.

package/docs/how-it-works.md

@@ -78,7 +78,7 @@ Event writes update a sibling `events/YYYY-MM-DD.index.json` file. The Markdown
 
 - Keep memory concise.
 - Prefer curated summaries over raw event history.
-- Give events a short `Keywords:` section; keywords weigh the most in search ranking. Older events with a `Cues:` section still search the same way.
+- Give events a short `Keywords:` section; keywords weigh the most in search ranking. `append_event` writes each keyword as a `[[keyword]]` wiki link, so a graph view such as Obsidian's groups events by topic. Install and upgrade convert clear keyword bullets in older events, including legacy `Cues:` sections, to this format and commit the change in the Lagoon; the next memory sync pushes it. A file is rewritten only if search reads exactly the same keywords from it afterwards.
 - Do not duplicate GitHub-owned facts such as commits, PRs, issues, reviews, or CI results.
 - Store artifact references plus the missing rationale, preference, assumption, or follow-up context.
 - Use project scope for project-specific state.
@@ -93,9 +93,9 @@ Agent: claude
 Session: mcp-a1b2c3d4
 
 Keywords:
-- local-first
-- token-free
-- install-story
+- [[local-first]]
+- [[token-free]]
+- [[install-story]]
 
 References:
 - commit: abc1234

package/docs/setup.md

@@ -16,7 +16,7 @@ npx hippocamp@latest install-codex
 npx hippocamp@latest install-grok
 ```
 
-Upgrade with the same command: `npx hippocamp@latest upgrade`. Installers default to `~/.lagoon` as the memory repo; pass `--global-root /absolute/path/to/lagoon` to use another clone.
+Upgrade with the same command: `npx hippocamp@latest upgrade`. When older events need it, an upgrade also brings them to the current keyword format, as one local Lagoon commit. Event files with uncommitted changes are left for a later upgrade. Restart your agents afterwards to load the new version. Installers default to `~/.lagoon` as the memory repo; pass `--global-root /absolute/path/to/lagoon` to use another clone.
 
 Installed through npx, the installer copies the package to `~/.hippocamp/<version>/` and registers that copy, so the server starts without npx or network and keeps working if npm cleans its cache. From a source checkout, `npm install` then `npm run install:claude` (or `install:codex`, `install:grok`) registers the checkout directly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippocamp",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "private": false,
   "description": "Local Git-backed memory for AI agents.",
   "license": "MIT",

package/scripts/hippocamp-memory.cjs

@@ -79,7 +79,20 @@ function getGlobalRoot() {
 }
 
 function getProjectRoot(projectRoot) {
-  return path.resolve(expandHomePath(projectRoot || process.env.HIPPOCAMP_PROJECT_ROOT || process.cwd()));
+  return path.resolve(expandHomePath(projectRoot || process.env.HIPPOCAMP_PROJECT_ROOT || getWorkingDirectory()));
+}
+
+// A long-running MCP server keeps its cwd after the worktree it started in is deleted.
+function getWorkingDirectory() {
+  try {
+    return process.cwd();
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+
+    throw new Error("The working directory no longer exists, likely a deleted worktree. Pass projectRoot.");
+  }
 }
 
 function findGitRootSync(startPath) {
@@ -140,7 +153,9 @@ function isProjectRepository(projectRoot) {
 }
 
 function slugifyProjectName(value) {
+  // macOS can report the same accented folder name in NFC or NFD form.
   const slug = value
+    .normalize("NFC")
     .toLowerCase()
     .replace(/[^a-z0-9._-]+/g, "-")
     .replace(/^-+|-+$/g, "");
@@ -297,7 +312,8 @@ function formatKeywordsSection(keywords) {
     return "";
   }
 
-  return ["Keywords:", ...normalizedKeywords.map((keyword) => `- ${keyword}`)].join("\n");
+  // Wiki links let Obsidian-style graph views group events by keyword.
+  return ["Keywords:", ...normalizedKeywords.map((keyword) => `- [[${keyword}]]`)].join("\n");
 }
 
 function normalizeAgentName(value) {
@@ -742,6 +758,72 @@ function parseEventBlocks(content) {
   });
 }
 
+// Older events used a "Cues:" header, inline comma lists, or plain bullets. Rewrite them in the
+// format append_event writes now: a "Keywords:" header and one [[wiki link]] bullet per keyword.
+// Only clear keyword bullets change: short, no spaces or backticks, before the first other line.
+function linkKeywordsInEventContent(content) {
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const lines = content.split(/\r?\n/);
+  const output = [];
+  let inKeywords = false;
+
+  for (const line of lines) {
+    const header = line.match(/^(\s*)(?:Keywords|Cues):\s*(.*?)\s*$/i);
+
+    if (header) {
+      const inline = normalizeKeywordList(splitInlineKeywordValues(header[2]));
+      output.push(`${header[1]}Keywords:`, ...inline.map((keyword) => `${header[1]}- [[${keyword}]]`));
+      inKeywords = true;
+      continue;
+    }
+
+    const bullet = inKeywords && line.match(/^(\s*-\s+)(.+?)\s*$/);
+
+    if (!bullet) {
+      inKeywords = false;
+      output.push(line);
+      continue;
+    }
+
+    const value = bullet[2];
+    const keyword = normalizeKeyword(value);
+    const plain = !value.startsWith("[[") && value.length <= 60 && !/[\s`]/.test(value);
+    output.push(plain && keyword ? `${bullet[1]}[[${keyword}]]` : line);
+  }
+
+  const linked = output.join(eol);
+  const sameKeywords = (text) => JSON.stringify(parseEventBlocks(text).map((event) => event.keywords));
+
+  // Never change what search reads: keep the file as it is if any keyword would differ.
+  return linked !== content && sameKeywords(linked) === sameKeywords(content) ? linked : content;
+}
+
+// Link keywords in every event file under the Lagoon root, except paths `skip` returns true for.
+// Reads every file before writing any. Returns the changed paths, relative to the root.
+async function linkEventKeywords(globalRoot, skip = () => false) {
+  const rewrites = [];
+
+  for (const relativePath of await walkMarkdownFiles(globalRoot)) {
+    if (!/(?:^|\/)events\/\d{4}-\d{2}-\d{2}\.md$/.test(relativePath) || skip(relativePath)) {
+      continue;
+    }
+
+    const absolutePath = path.join(globalRoot, relativePath);
+    const content = await fs.readFile(absolutePath, "utf8");
+    const linked = linkKeywordsInEventContent(content);
+
+    if (linked !== content) {
+      rewrites.push({ relativePath, absolutePath, linked });
+    }
+  }
+
+  for (const rewrite of rewrites) {
+    await fs.writeFile(rewrite.absolutePath, rewrite.linked);
+  }
+
+  return rewrites.map((rewrite) => rewrite.relativePath);
+}
+
 function buildEventIndex(markdownContent, markdownPath) {
   return {
     version: EVENT_INDEX_VERSION,
@@ -1627,6 +1709,7 @@ module.exports = {
   readMemoryFile,
   writeMemoryFile,
   appendEvent,
+  linkEventKeywords,
   listDirectoryEntries,
   searchMemory,
   readRecentEvents,

package/scripts/install-common.cjs

@@ -4,6 +4,7 @@ const os = require("node:os");
 const path = require("node:path");
 const { execFile } = require("node:child_process");
 const { promisify } = require("node:util");
+const { linkEventKeywords } = require("./hippocamp-memory.cjs");
 
 const execFileAsync = promisify(execFile);
 
@@ -43,6 +44,7 @@ async function git(args, cwd) {
 
 // Make sure the Lagoon memory repo exists, and say what is still missing for sync.
 // It never creates a remote or pushes: those reach outside this machine.
+// It may commit a local format upgrade of older events.
 async function prepareLagoon(globalRoot) {
   const hints = [];
   let created = false;
@@ -75,6 +77,33 @@ async function prepareLagoon(globalRoot) {
     hints.push('Set a Git identity so memory can be committed: git config --global user.name "Your Name" && git config --global user.email you@example.com');
   }
 
+  // Upgrades bring older events to the current keyword format: [[wiki links]] for graph views.
+  // Best effort, committed locally only; the next memory sync pushes it. Files with uncommitted
+  // or untracked changes are left alone, and a failed commit is undone so the next install retries.
+  let linked = [];
+
+  try {
+    const changes = await Promise.all([
+      git(["ls-files", "-z", "--modified", "--others", "--exclude-standard"], globalRoot),
+      git(["diff", "--cached", "--name-only", "-z"], globalRoot),
+    ]);
+    const known = changes.every((change) => change.ok);
+    const dirty = new Set(changes.flatMap((change) => change.stdout.split("\0").filter(Boolean)));
+    linked = await linkEventKeywords(globalRoot, (relativePath) => !known || dirty.has(relativePath));
+
+    if (linked.length) {
+      const commit = await git(["commit", "-m", "hippocamp: link event keywords", "--", ...linked], globalRoot);
+
+      if (!commit.ok) {
+        await git(["checkout", "--", ...linked], globalRoot);
+        linked = [];
+        hints.push("Older event keywords were not linked because Git could not commit. Run the upgrade again once Git is set up.");
+      }
+    }
+  } catch (error) {
+    hints.push(`Older event keywords were not linked: ${error.message}`);
+  }
+
   const remote = await git(["remote", "get-url", "origin"], globalRoot);
   let push = "no_remote";
 
@@ -88,7 +117,7 @@ async function prepareLagoon(globalRoot) {
     }
   }
 
-  return { root: globalRoot, created, remote: remote.ok ? remote.stdout : null, push, hints };
+  return { root: globalRoot, created, remote: remote.ok ? remote.stdout : null, push, linkedEvents: linked.length, hints };
 }
 
 function printHints(lagoon) {

package/test/install-common.test.cjs

@@ -127,3 +127,98 @@ test("prepareLagoon gives an empty folder inside another repo its own repo", asy
   assert.equal(result.created, true);
   assert.equal(fsSync.realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: nested }).toString().trim()), fsSync.realpathSync(nested));
 });
+
+test("prepareLagoon links older event keywords once and commits them locally", async (t) => {
+  useGitIdentity(t);
+  const lagoon = path.join(await tempDir(t, "link-keywords"), "lagoon");
+  const eventPath = path.join(lagoon, "projects", "demo", "events", "2026-05-01.md");
+  const notePath = path.join(lagoon, "projects", "demo", "notes.md");
+  const oldEvent = [
+    "# 2026-05-01",
+    "",
+    "## 09:00 - Inline cues",
+    "Cues: Mem0 removal, bare MCP",
+    "",
+    "## 10:00 - Bullet cues",
+    "Shipped it.",
+    "",
+    "Cues:",
+    "- pr-12",
+    "- [[already-linked]]",
+    "- `npm test` passed",
+    "",
+    "- a content bullet",
+    "",
+  ].join("\n");
+
+  await fs.mkdir(path.dirname(eventPath), { recursive: true });
+  await fs.writeFile(eventPath, oldEvent);
+  await fs.writeFile(notePath, "Cues: left, alone\n");
+  execFileSync("git", ["init", "-b", "main", lagoon]);
+  execFileSync("git", ["add", "."], { cwd: lagoon });
+  execFileSync("git", ["commit", "-m", "init"], { cwd: lagoon });
+
+  const first = await prepareLagoon(lagoon);
+  const linked = await fs.readFile(eventPath, "utf8");
+
+  assert.equal(first.linkedEvents, 1);
+  assert.match(linked, /## 09:00 - Inline cues\nKeywords:\n- \[\[mem0-removal\]\]\n- \[\[bare-mcp\]\]\n/);
+  assert.match(linked, /Keywords:\n- \[\[pr-12\]\]\n- \[\[already-linked\]\]\n- `npm test` passed\n\n- a content bullet\n/);
+  assert.equal(await fs.readFile(notePath, "utf8"), "Cues: left, alone\n");
+  assert.equal(execFileSync("git", ["status", "--porcelain"], { cwd: lagoon, encoding: "utf8" }), "");
+  assert.equal(execFileSync("git", ["log", "-1", "--format=%s"], { cwd: lagoon, encoding: "utf8" }).trim(), "hippocamp: link event keywords");
+
+  const second = await prepareLagoon(lagoon);
+
+  assert.equal(second.linkedEvents, 0);
+  assert.equal(execFileSync("git", ["rev-list", "--count", "HEAD"], { cwd: lagoon, encoding: "utf8" }).trim(), "2");
+});
+
+test("prepareLagoon leaves dirty event files alone and links CRLF events without duplicates", async (t) => {
+  useGitIdentity(t);
+  const lagoon = path.join(await tempDir(t, "link-dirty"), "lagoon");
+  const events = path.join(lagoon, "events");
+  const crlfPath = path.join(events, "2026-05-01.md");
+  const dirtyPath = path.join(events, "2026-05-02.md");
+  const untrackedPath = path.join(events, "2026-05-03.md");
+
+  await fs.mkdir(events, { recursive: true });
+  await fs.writeFile(crlfPath, "# 2026-05-01\r\n\r\n## 09:00 - CRLF\r\nCues: bare MCP, Bare MCP\r\n");
+  await fs.writeFile(dirtyPath, "## 09:00 - Dirty\nCues:\n- pr-1\n");
+  execFileSync("git", ["init", "-b", "main", lagoon]);
+  execFileSync("git", ["add", "."], { cwd: lagoon });
+  execFileSync("git", ["commit", "-m", "init"], { cwd: lagoon });
+  await fs.appendFile(dirtyPath, "- user-edit\n");
+  await fs.writeFile(untrackedPath, "## 09:00 - Untracked\nCues:\n- pr-2\n");
+
+  const result = await prepareLagoon(lagoon);
+
+  assert.equal(result.linkedEvents, 1);
+  assert.equal(await fs.readFile(crlfPath, "utf8"), "# 2026-05-01\r\n\r\n## 09:00 - CRLF\r\nKeywords:\r\n- [[bare-mcp]]\r\n");
+  assert.equal(await fs.readFile(dirtyPath, "utf8"), "## 09:00 - Dirty\nCues:\n- pr-1\n- user-edit\n");
+  assert.equal(await fs.readFile(untrackedPath, "utf8"), "## 09:00 - Untracked\nCues:\n- pr-2\n");
+  assert.equal(execFileSync("git", ["show", "--name-only", "--format=", "HEAD"], { cwd: lagoon, encoding: "utf8" }).trim(), "events/2026-05-01.md");
+});
+
+test("prepareLagoon undoes linked keywords when Git cannot commit them", async (t) => {
+  useGitIdentity(t);
+  const lagoon = path.join(await tempDir(t, "link-no-commit"), "lagoon");
+  const eventPath = path.join(lagoon, "events", "2026-05-01.md");
+  const oldEvent = "## 09:00 - Old\nCues:\n- pr-1\n";
+
+  await fs.mkdir(path.dirname(eventPath), { recursive: true });
+  await fs.writeFile(eventPath, oldEvent);
+  execFileSync("git", ["init", "-b", "main", lagoon]);
+  execFileSync("git", ["add", "."], { cwd: lagoon });
+  execFileSync("git", ["commit", "-m", "init"], { cwd: lagoon });
+  const hook = path.join(lagoon, ".git", "hooks", "pre-commit");
+  await fs.writeFile(hook, "#!/bin/sh\nexit 1\n");
+  await fs.chmod(hook, 0o755);
+
+  const result = await prepareLagoon(lagoon);
+
+  assert.equal(result.linkedEvents, 0);
+  assert.equal(await fs.readFile(eventPath, "utf8"), oldEvent);
+  assert.equal(execFileSync("git", ["status", "--porcelain"], { cwd: lagoon, encoding: "utf8" }), "");
+  assert.ok(result.hints.some((hint) => /could not commit/.test(hint)));
+});

package/test/memory-efficiency.test.cjs

@@ -662,3 +662,57 @@ test("an empty folder has no project and uses global memory", async (t) => {
   // A folder that does not exist keeps its name, as Dream's synthetic roots do.
   assert.equal(memory.getProjectSlug(path.join(tempRoot, "missing")), "missing");
 });
+
+test("Project slug is the same for NFC and NFD folder names", () => {
+  const name = "Génération IA";
+  assert.equal(memory.getProjectSlug(`/tmp/${name.normalize("NFC")}`), "g-n-ration-ia");
+  assert.equal(memory.getProjectSlug(`/tmp/${name.normalize("NFD")}`), "g-n-ration-ia");
+});
+
+test("A deleted working directory asks for projectRoot", async (t) => {
+  const originalCwd = process.cwd();
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-deleted-cwd-"));
+  t.after(() => process.chdir(originalCwd));
+  process.chdir(tempRoot);
+  await fs.rm(tempRoot, { recursive: true });
+
+  assert.throws(() => memory.getProjectRoot(), /Pass projectRoot/);
+});
+
+test("event keywords are written as wiki links and still indexed as plain keywords", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-wiki-links-"));
+  const projectRoot = path.join(tempRoot, "wiki-links-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 event = await memory.appendEvent({
+    content: "Graph views group events by keyword.",
+    keywords: ["Knowledge Graph", "obsidian"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    timestamp: "2026-10-16T09:00:00.000Z",
+    title: "Graph note",
+  });
+
+  const content = await fs.readFile(path.join(event.root, event.path), "utf8");
+  const index = JSON.parse(await fs.readFile(event.indexPath, "utf8"));
+
+  assert.match(content, /Keywords:\n- \[\[knowledge-graph\]\]\n- \[\[obsidian\]\]/);
+  assert.match(JSON.stringify(index), /"knowledge-graph"/);
+  assert.doesNotMatch(JSON.stringify(index), /\[\[/);
+
+  const search = await memory.searchMemory({ projectRoot, query: "obsidian", scope: "project" });
+
+  assert.deepEqual(search.results[0].keywords, ["knowledge-graph", "obsidian"]);
+});