hippocamp 0.2.13 → 0.2.14

package/AGENTS.md

@@ -45,7 +45,7 @@ This repository is a local-first MCP package for Git-backed agent memory. Keep c
 - `assets/railway/run-dream.sh`: short-lived hosted Dream runner that clones Lagoon and opens one Dream PR per project.
 - `Dockerfile.railway` and `railway.json`: optional Railway cron deployment for overnight Dream runs.
 - `assets/brand/hippocamp-mascot.png`: README mascot asset.
-- `assets/brand/hippocamp-demo.gif`: README demo, loaded from GitHub and kept out of the npm package by `.npmignore` (keep `.npmignore` in sync with `.gitignore`).
+- `assets/brand/lagoon-graph.jpg`: README Obsidian graph view of a real Lagoon, loaded from GitHub and kept out of the npm package by `.npmignore` (keep `.npmignore` in sync with `.gitignore`).
 - `docs/`: user docs (setup, how it works, Dream, results, development). The README stays a short overview that links to them.
 
 ## Project Invariants

package/README.md

@@ -18,9 +18,11 @@ npx hippocamp@latest install
 
 This installs Hippocamp into every supported agent it finds and creates your memory repo, `~/.lagoon`. Restart your agent and it starts each task by waking up from memory.
 
-![Codex saves a team decision to Hippocamp on its own; a later Claude Code session finds it with search_memory; git log shows the commit](https://raw.githubusercontent.com/guillaumegay13/hippocamp/main/assets/brand/hippocamp-demo.gif)
+## Build and own your agents' memory
 
-A replay of a real session. Neither prompt mentions Hippocamp.
+![A real Lagoon in Obsidian's graph view: thousands of agent-written events linked by shared keywords](https://raw.githubusercontent.com/guillaumegay13/hippocamp/main/assets/brand/lagoon-graph.jpg)
+
+A real `~/.lagoon` opened in Obsidian. Every dot is a Markdown note your agents wrote, linked by keywords. It's plain files in your own Git repo, so you can open them in any editor.
 
 ## Why Hippocamp?
 
@@ -55,6 +57,10 @@ Reproducible with the scripts in this repo.
 | Work continuity, 21 real Claude Code sessions, checks passed | 100% (20 / 20) | Claude Code native memory: 96% (25 / 26) |
 | Work continuity, same 21 sessions in Codex, checks passed | 86% (24 / 28) | Codex native memory: 86% (24 / 28) |
 
+**Work continuity** tests memory on real engineering work, not chat questions. A real Claude Code or Codex agent works through 21 coding sessions on two small projects. Early sessions establish facts, such as a rejected library, a pinned Node version, a blocked vendor, a parked branch or a user preference. Later tickets only go well if the agent remembers them, and the prompts never mention memory. A blind judge grades 28 checks from the diff and the tool calls. Each arm is installed the way a developer has it.
+
+The same Hippocamp server, plugged into either agent with no changes, keeps up with that agent's own memory. In Codex, whose built-in memory stored almost nothing, Hippocamp's memory covered 57% of the planted facts against 4%. Hippocamp uses about 25–45% more tokens per session. This is one run per arm, so the differences are within noise. Every grade, diff and judge prompt is published in [docs/results](docs/results/).
+
 Full tables, method, and limits: [docs/results.md](docs/results.md).
 
 ## Docs

package/docs/how-it-works.md

@@ -70,7 +70,7 @@ Typical agent flow:
 4. Use `append_event` for meaningful milestones, with a title and 1-8 concise keywords.
 5. Update curated files like `current_state.md` and `open_threads.md` before finishing.
 
-Writes sync by default. If sync fails or is skipped, call `sync_memory`.
+Writes sync by default. If sync fails or is skipped, call `sync_memory`. `wake_up` and a `sync_memory` with nothing to send first pull what other machines pushed (fast-forward only, without credential prompts; when the remote cannot be reached, the pull gives up after 10 seconds and the agent continues with local memory), so a second machine starts from current memory. Sync only commits when the Lagoon is the top of its own Git repository; a Lagoon folder inside another repository, such as a code checkout, is never committed or pushed.
 
 Event writes update a sibling `events/YYYY-MM-DD.index.json` file. The Markdown event remains the canonical memory; the sidecar is rebuildable. Search ranks indexed events and curated files with BM25 and typo tolerance ([MiniSearch](https://github.com/lucaong/minisearch)), weighting keywords above titles and titles above bodies. It returns small coherent evidence blocks from indexed events; an event found only by its keywords or title returns its first paragraphs. If no indexed result is strong enough, it returns no event result instead of scanning whole event logs.
 

package/docs/results.md

@@ -43,7 +43,7 @@ The same reader reaches 90% with the correct sessions, so the remaining gap is r
 
 Does memory carry real engineering work from one coding session to the next? `npm run eval:continuity` runs real headless Claude Code (`claude-opus-5-5`, Claude Code 2.1.318 to 2.1.319) through 21 sessions over two small synthetic projects (a TypeScript webhook relay and a Python ingest job). Early sessions plant facts the way work does: a rejected library, a pinned Node version, a blocked vendor, a parked branch, a user preference. Later sessions give tickets that only go well if the agent remembers them. The prompts never say "remember" or point at memory.
 
-In short: the same Hippocamp server, plugged unchanged into Claude Code or Codex, keeps up with each one's own memory (100% vs 96% in Claude Code, 86% vs 86% in Codex), with fewer than 5 points of difference and one run per arm. In Codex, whose built-in memory stored almost nothing, Hippocamp's memory covered 35% of the planted facts against 4%.
+In short: the same Hippocamp server, plugged unchanged into Claude Code or Codex, keeps up with each one's own memory (100% vs 96% in Claude Code, 86% vs 86% in Codex), with fewer than 5 points of difference and one run per arm. In Codex, whose built-in memory stored almost nothing, Hippocamp's memory covered 57% of the planted facts against 4%.
 
 Each arm is installed the way a developer has it, in its own sandbox home: Claude Code defaults with native auto-memory, or Hippocamp through its real installer (`install-claude`) with auto-memory off. A blind judge (Opus, arm names and memory paths scrubbed) grades 28 checks against the diff and the tool calls. A check is n/a when the session wrote no code it applies to.
 
@@ -56,11 +56,11 @@ Run `full-1`, one run per arm:
 | Tokens per session, median | 179k | 224k |
 | Time per session, median | 62 s | 73 s |
 | Agent cost per run, API price | $8.84 | $9.19 |
-| Memory entries at the end | 8 | 15 |
-| Planted facts covered by memory | 22% | 30% |
-| Memory entries that are useful (precision) | 88% | 80% |
+| Memory entries at the end | 8 | 27 |
+| Planted facts covered by memory | 22% | 57% |
+| Memory entries that are useful (precision) | 88% | 81% |
 
-What it shows: Hippocamp, plugged into Claude Code as a plain MCP server, does as well as Claude Code's own memory, at about the same cost (+4% dollars, +25% tokens per session). Native memory's one miss was a parked `fix/late-dedupe` branch it no longer knew about, so it rewrote the fix from scratch. Hippocamp's 8 n/a checks come mostly from one session where it correctly held a blocked vendor back and wrote no code; native also held the vendor back, but with gated code the checks could grade.
+What it shows: Hippocamp, plugged into Claude Code as a plain MCP server, does as well as Claude Code's own memory, at about the same cost (+4% dollars, +25% tokens per session). Native memory's one miss was a parked `fix/late-dedupe` branch it no longer knew about, so it rewrote the fix from scratch. Hippocamp's 8 n/a checks come mostly from one session where it correctly held a blocked vendor back and wrote no code; native also held the vendor back, but with gated code the checks could grade. A check is only counted when the session did work it applies to, so the two arms are scored on different numbers of checks (20 vs 26); this favors an arm that holds work back.
 
 What it does not show: that Hippocamp is better. The difference is one check, from one run per arm (bootstrap 95% interval over probes: +4 points, 0 to +16). There is no no-memory run, so the "needing memory" label comes from the dataset, not from a measured baseline. An earlier development run (27 / 27 vs 24 / 27) is not used: its cases were added after a tie and its harness was unfair to native memory.
 
@@ -77,16 +77,20 @@ Run `codex-1` repeats the 21 sessions in Codex (`codex exec`, codex-cli 0.159.2,
 | Tokens per session, median | 166k | 238k |
 | Time per session, median | 63 s | 82 s |
 | Memory calls per session | 1.0 | 4.9 |
-| Memory entries at the end | 4 | 17 |
-| Planted facts covered by memory | 4% | 35% |
-| Memory entries that are useful (precision) | 25% | 76% |
+| Memory entries at the end | 4 | 31 |
+| Planted facts covered by memory | 4% | 57% |
+| Memory entries that are useful (precision) | 25% | 61% |
 
-What it shows: the same Hippocamp server, with no Codex-specific code, works in Codex as it does in Claude Code. Codex called `wake_up`, `search_memory` and `append_event` on its own, and the memory it built covers about as many planted facts as in Claude Code (35% vs 30%). The two Codex arms tie on checks (bootstrap: 0 points, -14 to +14).
+What it shows: the same Hippocamp server, with no Codex-specific code, works in Codex as it does in Claude Code. Codex called `wake_up`, `search_memory` and `append_event` on its own, and the memory it built covers as many planted facts as in Claude Code (57% in both). The two Codex arms tie on checks (bootstrap: 0 points, -14 to +14).
 
-Codex's own memory stored almost nothing in this run: its background summaries never produced a memory from a past session, and the one real entry is a changelog preference the agent wrote as a note. The other three entries are Codex's empty templates, which the judge counts as noise. Codex still passed most checks without it, from the repository itself (code, commit messages, notes it wrote in the repo); that is why the score does not drop more. Hippocamp's misses include one stale next step and one fact it never saved (a blocked vendor).
+Codex's own memory stored almost nothing in this run: its background summaries never produced a memory from a past session, and the one real entry is a changelog preference the agent wrote as a note. The other three entries are Codex's empty templates, which the judge counts as noise. The harness turns Codex memory on but does not wait for or confirm its background step between sessions, so this arm measures Codex memory as it behaved here, not a verified working pipeline. Hippocamp's Codex memory also holds more duplicates (5) and stale entries (4) than in Claude Code, so its precision is lower (61%). Codex still passed most checks without it, from the repository itself (code, commit messages, notes it wrote in the repo); that is why the score does not drop more. Hippocamp's misses include one stale next step and one fact it never saved (a blocked vendor).
 
 Codex reports no dollar cost, so this run has token and time numbers only.
 
+### How memory quality is scored
+
+At the end of each run, a judge labels every memory entry, across both projects, as a current fact, a stale fact, other useful context, noise or a duplicate. Coverage is the share of planted facts with at least one current entry. Each entry is credited with one fact at most, so a native memory file that lists several facts in one entry gets credit for one of them: coverage favors memories that store one fact per entry, like Hippocamp's events, and the native coverage figures are a lower bound. A first version of this report judged only one project of Hippocamp's memory and gave it 30% (Claude Code) and 35% (Codex); this was fixed and re-judged without re-running any session.
+
 The run data is in [results/continuity-codex-1](results/continuity-codex-1/).
 
 ## Why less text matters

package/package.json

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

package/scripts/hippocamp-memory.cjs

@@ -438,9 +438,9 @@ async function ensureParentDirectory(filePath) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
 }
 
-async function runGit(args, cwd) {
+async function runGit(args, cwd, options = {}) {
   try {
-    const result = await execFileAsync("git", args, { cwd });
+    const result = await execFileAsync("git", args, { cwd, ...options });
     return {
       ok: true,
       stdout: result.stdout.trim(),
@@ -477,17 +477,54 @@ function realpathExisting(targetPath) {
   }
 }
 
-async function syncMemory({ scope, projectRoot, paths, message }) {
+// The Lagoon's own repository, or null: a repository that only encloses the Lagoon (a code
+// checkout, a home-directory repo) must never receive memory commits or pushes.
+async function getLagoonRepo() {
   const repoCandidate = getGlobalRepoRoot();
   const repoRoot = await getGitRepoRoot(repoCandidate);
-  const scopeRoot = getScopeRoot(scope, projectRoot);
 
   if (!repoRoot) {
+    return { repoCandidate, reason: "not_git_repo" };
+  }
+
+  if (realpathExisting(repoRoot) !== realpathExisting(repoCandidate)) {
+    return { repoCandidate, repoRoot, reason: "lagoon_not_repo_root" };
+  }
+
+  return { repoCandidate, repoRoot };
+}
+
+// Brings in memory pushed from other machines. Fast-forward only: local commits that have not
+// been pushed yet are reconciled by the push path, never here. Offline or slow remotes are skipped.
+async function pullMemory() {
+  const { repoRoot, reason } = await getLagoonRepo();
+
+  if (!repoRoot) {
+    return { pulled: false, reason };
+  }
+
+  const upstream = await runGit(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], repoRoot);
+
+  if (!upstream.ok) {
+    return { pulled: false, reason: "no_upstream" };
+  }
+
+  // Never prompt: saved credentials (credential helpers, SSH agent) still work; anything that would ask fails fast.
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "true", SSH_ASKPASS: "true", GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || "ssh -o BatchMode=yes" };
+  const result = await runGit(["pull", "--ff-only", "--quiet"], repoRoot, { timeout: 10000, env });
+  return result.ok ? { pulled: true } : { pulled: false, reason: "pull_failed", error: result.stderr };
+}
+
+async function syncMemory({ scope, projectRoot, paths, message }) {
+  const { repoCandidate, repoRoot, reason } = await getLagoonRepo();
+  const scopeRoot = getScopeRoot(scope, projectRoot);
+
+  if (reason) {
     return {
       attempted: false,
       skipped: true,
-      reason: "not_git_repo",
-      repoRoot: repoCandidate,
+      reason,
+      repoRoot: repoRoot || repoCandidate,
     };
   }
 
@@ -530,11 +567,13 @@ async function syncMemory({ scope, projectRoot, paths, message }) {
     const aheadResult = await runGit(["rev-list", "--count", "@{u}..HEAD"], repoRoot);
 
     if (!aheadResult.ok || aheadResult.stdout === "0") {
+      // Nothing to send: an explicit sync still brings in what other machines pushed.
       return {
         attempted: true,
         skipped: true,
         reason: "no_changes_to_commit",
         repoRoot,
+        pull: await pullMemory(),
       };
     }
 
@@ -1084,7 +1123,10 @@ async function readMemoryFile({ scope, path: relativePath, projectRoot }) {
 async function writeMemoryFile({ scope, path: relativePath, content, projectRoot, sync = true }) {
   const target = resolveScopedPath(scope, relativePath, projectRoot);
 
-  if (target.path === "events" || target.path.startsWith("events/")) {
+  // Event logs are append-only in every scope, including a project's log reached from the global root.
+  const fromGlobal = path.relative(getGlobalRoot(), target.absolutePath).split(path.sep);
+
+  if (target.path === "events" || target.path.startsWith("events/") || fromGlobal[0] === "events" || (fromGlobal[0] === "projects" && fromGlobal[2] === "events")) {
     throw new Error("events/ is append-only. Use append_event with a title and keywords instead.");
   }
 
@@ -1273,7 +1315,8 @@ async function collectEventDocuments({ scope, eventFiles }) {
       index = null;
     }
 
-    const markdownName = typeof index?.path === "string" ? index.path : indexName.replace(/\.index\.json$/, ".md");
+    // The log always sits next to its index; a path field inside the index is never trusted.
+    const markdownName = indexName.replace(/\.index\.json$/, ".md");
 
     if (!index || !Array.isArray(index.events)) {
       continue;
@@ -1622,6 +1665,7 @@ async function searchMemory({ query, scope = "both", projectRoot, maxResults = 5
 }
 
 async function wakeUp({ projectRoot } = {}) {
+  const pull = await pullMemory();
   const globalRoot = getScopeRoot("global", projectRoot);
   const resolvedProjectRoot = getProjectRoot(projectRoot);
   const projectSlug = getProjectSlug(projectRoot);
@@ -1695,6 +1739,7 @@ async function wakeUp({ projectRoot } = {}) {
     missing,
     globalFiles: globalFiles.map((file) => file.path),
     projectFiles: projectFiles.map((file) => file.path),
+    pull,
     text: `${sections.join("\n").trim()}\n`,
   };
 }