hippocamp 0.2.9 → 0.2.11

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. Older events with plain keywords or a `Cues:` section still search the same way.
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippocamp",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "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) {
@@ -510,12 +526,19 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
   }
 
   if (!diffResult.stdout) {
-    return {
-      attempted: true,
-      skipped: true,
-      reason: "no_changes_to_commit",
-      repoRoot,
-    };
+    // Commits left behind by an earlier failed push still need to go up.
+    const aheadResult = await runGit(["rev-list", "--count", "@{u}..HEAD"], repoRoot);
+
+    if (!aheadResult.ok || aheadResult.stdout === "0") {
+      return {
+        attempted: true,
+        skipped: true,
+        reason: "no_changes_to_commit",
+        repoRoot,
+      };
+    }
+
+    return pushToUpstream(repoRoot, { attempted: true, committed: false, repoRoot });
   }
 
   const commitResult = await runGit(["commit", "-m", message, "--", ...repoRelativePaths], repoRoot);
@@ -524,16 +547,22 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
     throw new Error(commitResult.stderr || "git commit failed.");
   }
 
+  return pushToUpstream(repoRoot, {
+    attempted: true,
+    committed: true,
+    repoRoot,
+    commitSummary: commitResult.stdout,
+  });
+}
+
+async function pushToUpstream(repoRoot, result) {
   const upstreamResult = await runGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], repoRoot);
 
   if (!upstreamResult.ok) {
     return {
-      attempted: true,
-      committed: true,
+      ...result,
       pushed: false,
       reason: "no_upstream",
-      repoRoot,
-      commitSummary: commitResult.stdout,
     };
   }
 
@@ -544,12 +573,9 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
 
     if (!pullResult.ok) {
       return {
-        attempted: true,
-        committed: true,
+        ...result,
         pushed: false,
         reason: "pull_rebase_failed",
-        repoRoot,
-        commitSummary: commitResult.stdout,
         pushError: pushResult.stderr,
         pullError: pullResult.stderr,
       };
@@ -559,23 +585,17 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
 
     if (!pushResult.ok) {
       return {
-        attempted: true,
-        committed: true,
+        ...result,
         pushed: false,
         reason: "push_failed",
-        repoRoot,
-        commitSummary: commitResult.stdout,
         pushError: pushResult.stderr,
       };
     }
   }
 
   return {
-    attempted: true,
-    committed: true,
+    ...result,
     pushed: true,
-    repoRoot,
-    commitSummary: commitResult.stdout,
     pushSummary: pushResult.stdout || pushResult.stderr,
   };
 }

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"]);
+});

package/test/sync-memory.test.cjs

@@ -63,3 +63,57 @@ test("sync commits when the Lagoon path goes through a symlink", async (t) => {
     /escapes the memory root/,
   );
 });
+
+test("sync pushes commits left behind by an earlier failed push", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-backlog-"));
+  const remote = path.join(tempRoot, "remote.git");
+  const lagoon = path.join(tempRoot, "lagoon");
+  const projectRoot = path.join(tempRoot, "project");
+  const git = (args, cwd = lagoon) => execFileSync("git", args, { cwd }).toString().trim();
+
+  const identity = { GIT_AUTHOR_NAME: "Test", GIT_AUTHOR_EMAIL: "test@example.com", GIT_COMMITTER_NAME: "Test", GIT_COMMITTER_EMAIL: "test@example.com" };
+  const saved = Object.fromEntries(Object.keys(identity).map((key) => [key, process.env[key]]));
+  Object.assign(process.env, identity);
+  t.after(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  git(["init", "-q", "--bare", "-b", "main", remote], tempRoot);
+  git(["clone", "-q", remote, lagoon], tempRoot);
+  git(["commit", "-q", "--allow-empty", "-m", "init"]);
+  git(["push", "-q", "-u", "origin", "main"]);
+  process.env.HIPPOCAMP_GLOBAL_ROOT = lagoon;
+  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, maxRetries: 5 });
+  });
+
+  // Simulate an unreachable remote for the first write.
+  git(["remote", "set-url", "origin", path.join(tempRoot, "missing.git")]);
+  const write = await memory.appendEvent({ content: "Use HTTPS.", keywords: ["sync"], projectRoot, scope: "project", title: "Remote" });
+  assert.equal(write.sync.committed, true);
+  assert.equal(write.sync.pushed, false);
+
+  git(["remote", "set-url", "origin", remote]);
+  const result = await memory.syncMemory({
+    scope: "project",
+    projectRoot,
+    paths: await memory.getDefaultSyncPaths("project", projectRoot),
+    message: "sync",
+  });
+
+  assert.equal(result.committed, false);
+  assert.equal(result.pushed, true);
+  assert.equal(git(["rev-parse", "main"], remote), git(["rev-parse", "HEAD"]));
+});