hippocamp 0.2.6 → 0.2.8

package/.github/workflows/publish.yml

@@ -4,6 +4,7 @@ on:
   release:
     types:
       - published
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -11,6 +12,7 @@ permissions:
 
 jobs:
   publish:
+    if: github.event_name == 'release'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -25,3 +27,26 @@ jobs:
       - name: Verify release tag matches package version
         run: test "$GITHUB_REF_NAME" = "v$(node -p "require('./package.json').version")"
       - run: npm publish
+
+  github-packages:
+    # Mirror of the npm package on GitHub Packages, so the repository lists it.
+    # npmjs.com stays the install path; GitHub's npm registry needs a token to install.
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://npm.pkg.github.com"
+          package-manager-cache: false
+      - name: Scope the package name for GitHub Packages
+        run: |
+          npm pkg set name="@${GITHUB_REPOSITORY_OWNER}/hippocamp"
+          npm pkg set repository.url="https://github.com/${GITHUB_REPOSITORY}"
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/AGENTS.md

@@ -47,15 +47,15 @@ This repository is a local-first MCP package for Git-backed agent memory. Keep c
 - Sync paths must stay under the selected Lagoon memory root.
 - 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.
-- Event logs are append-only daily Markdown files under `events/YYYY-MM-DD.md`, with sibling `events/YYYY-MM-DD.index.json` cue indexes.
+- 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.
 - Curated files such as `current_state.md` and `open_threads.md` use explicit file writes.
-- MCP `append_event` requires a title and 1-8 cues; MCP `write_memory_file` rejects paths under `events/`; an explicit `projectRoot` must be a directory inside a Git repository.
+- 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.
 - Default sync is automatic through the local Lagoon repo.
 - Local MCP mode must not require `GITHUB_TOKEN`, GitHub App auth, or a cloud service.
 - Memory must not duplicate facts already tracked by GitHub commits, PRs, issues, reviews, or CI. Store references plus the missing rationale, preference, assumption, or follow-up context instead.
-- Dream compaction sends `current_state.md`, `open_threads.md`, and bounded cue-indexed event evidence for open-thread decisions. It must not dump full event logs, cue indexes, or raw GitHub-owned facts into the model prompt.
+- Dream maintains `current_state.md` and `open_threads.md` using bounded recent indexed events and open-thread evidence. It must not dump full event logs, keyword indexes, or raw GitHub-owned facts into the model prompt. Preserve the `hippocamp-dream-through` comment in current state; it tracks the last reviewed event without another file.
 - Dream must compact coherent Markdown snapshots and fail without writing when the snapshot cannot fit. It must not crop wake-up files.
 - The Dream GitHub Actions workflow is a Lagoon repo template. It should remain schedule-only and create PRs rather than pushing directly to `main`. Auto-merge is allowed only for repositories named `lagoon` after exact changed-file validation.
 - The Railway Dream deployment is optional infrastructure. It must exit after each run, keep credentials in environment variables, and preserve the same PR policy.
@@ -84,5 +84,5 @@ 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 coherent compaction, current/open curated files plus bounded thread evidence, one PR per project.
+- 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.

package/README.md

@@ -1,6 +1,6 @@
 # Hippocamp
 
-[![npm](https://img.shields.io/npm/v/hippocamp)](https://www.npmjs.com/package/hippocamp) [![CI](https://github.com/guillaumegay13/hippocamp/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaumegay13/hippocamp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/hippocamp)](https://www.npmjs.com/package/hippocamp) [![npm downloads](https://img.shields.io/npm/dm/hippocamp)](https://www.npmjs.com/package/hippocamp) [![CI](https://github.com/guillaumegay13/hippocamp/actions/workflows/ci.yml/badge.svg)](https://github.com/guillaumegay13/hippocamp/actions/workflows/ci.yml)
 
 <p align="center">
   <img src="./assets/brand/hippocamp-mascot.png" alt="Hippocamp mascot" width="220" />
@@ -24,12 +24,24 @@ A replay of a real session. Neither prompt mentions Hippocamp.
 
 ## Why Hippocamp?
 
-- **Written by the agent itself.** The agent doing the work decides what is worth keeping, in its own words. Unlike memory services that run a second model to extract facts, nothing rewrites it behind your back: events are saved as written, and optional Dream compaction of the two summary files arrives as a pull request you review.
+- **Written by the agent itself.** The agent doing the work records what is worth keeping, in its own words. Events stay as written. Optional Dream reviews recent events to update and compact the two summary files, promoting supported lessons through a pull request you review.
 - **One memory for every agent.** Claude Code, Codex, and your other agents share the same repo. Built-in memory, like Claude Code's or Codex's, stays inside one tool.
 - **History you can audit.** Every memory is a Git commit. Roll back a bad memory like bad code.
 - **Files you own.** Plain Markdown, readable without any UI, synced across machines with your normal Git credentials.
 - **Nothing to sign up for.** No vendor that can change terms or shut down.
 
+## Compared with other memory tools
+
+| | **Hippocamp** | [Mem0](https://docs.mem0.ai) | [Zep](https://www.getzep.com) | [Graphiti](https://github.com/getzep/graphiti) | [Letta Code](https://github.com/letta-ai/letta-code) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | Claude Code / Codex built-in |
+| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| Agent agnostic (MCP server) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
+| Plain files you own | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
+| Auditable history | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
+| No extra account, API key, or model | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
+| Syncs through your own Git | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Always free | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
+| Open source | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
+
 ## Results
 
 Reproducible with the scripts in this repo.
@@ -47,7 +59,7 @@ Full tables, method, and limits: [docs/results.md](docs/results.md).
 
 - [Setup](docs/setup.md): install options, the Lagoon repo, a private remote, configuration
 - [How it works](docs/how-it-works.md): memory layout, MCP tools, memory rules
-- [Dream](docs/dream.md): optional overnight compaction as a reviewed pull request
+- [Dream](docs/dream.md): optional overnight memory updates and compaction as a reviewed pull request
 - [Results](docs/results.md): evals and how to rerun them
 - [Development](docs/development.md): commands and releases
 

package/assets/github-actions/hippocamp-dream.yml

@@ -3,7 +3,6 @@ name: Hippocamp Dream
 on:
   schedule:
     - cron: "17 3 * * *"
-  workflow_dispatch:
 
 permissions:
   contents: write
@@ -42,7 +41,7 @@ jobs:
           git config user.name "hippocamp-dream[bot]"
           git config user.email "hippocamp-dream[bot]@users.noreply.github.com"
 
-      - name: Find projects over threshold
+      - name: Find projects needing Dream
         run: |
           npx -y hippocamp@latest dream \
             --all \
@@ -115,7 +114,7 @@ jobs:
             fi
 
             git add "projects/${project}/current_state.md" "projects/${project}/open_threads.md"
-            git commit -m "Dream compact ${project} memory"
+            git commit -m "Dream update ${project} memory"
             git push --force-with-lease origin "$branch"
 
             node - "$project" "/tmp/hippocamp-dream-${project}.json" > "/tmp/hippocamp-dream-${project}.md" <<'NODE'
@@ -124,7 +123,7 @@ jobs:
           const payload = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
           const result = payload.results[0];
           const lines = [
-            `Dream compacted \`${project}\` curated memory.`,
+            `Dream updated \`${project}\` curated memory.`,
             "",
             "Before:",
             `- wake_up: ${result.wakeUpChars} chars`,
@@ -132,6 +131,7 @@ jobs:
             `- open_threads.md: ${result.files["open_threads.md"]} bytes`,
             "",
             "Context:",
+            `- new event excerpts: ${result.context.recentEvents}`,
             `- open threads found: ${result.context.openThreads}`,
             `- threads with event evidence: ${result.context.threadsWithEvidence}`,
             `- event evidence snippets: ${result.context.evidenceItems}`,
@@ -144,15 +144,15 @@ jobs:
             "",
             "Policy:",
             "- touched only `current_state.md` and `open_threads.md`",
-            "- used bounded cue-indexed event evidence for thread decisions",
-            "- did not modify append-only events or cue indexes",
-            "- moved historical detail out of wake-up context",
+            "- used bounded recent and thread evidence to update project memory",
+            "- did not modify append-only events or keyword indexes",
+            "- preserved supported lessons and remaining actions within the size budget",
           ];
           console.log(lines.join("\n"));
           NODE
 
             existing="$(gh pr list --head "$branch" --state open --json number --jq '.[0].number // empty')"
-            title="Dream compact ${project} memory"
+            title="Dream update ${project} memory"
 
             if [ -n "$existing" ]; then
               gh pr edit "$existing" --title "$title" --body-file "/tmp/hippocamp-dream-${project}.md"

package/assets/railway/run-dream.sh

@@ -119,7 +119,7 @@ while IFS= read -r project; do
   fi
 
   git add "projects/${project}/current_state.md" "projects/${project}/open_threads.md"
-  git commit -m "Dream compact ${project} memory"
+  git commit -m "Dream update ${project} memory"
 
   if git ls-remote --exit-code --heads origin "refs/heads/${branch}" >/dev/null 2>&1; then
     git fetch origin "refs/heads/${branch}:refs/remotes/origin/${branch}"
@@ -133,7 +133,7 @@ const project = process.argv[2];
 const payload = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
 const result = payload.results[0];
 const lines = [
-  `Dream compacted \`${project}\` curated memory.`,
+  `Dream updated \`${project}\` curated memory.`,
   "",
   "Before:",
   `- wake_up: ${result.wakeUpChars} chars`,
@@ -141,6 +141,7 @@ const lines = [
   `- open_threads.md: ${result.files["open_threads.md"]} bytes`,
   "",
   "Context:",
+  `- new event excerpts: ${result.context.recentEvents}`,
   `- open threads found: ${result.context.openThreads}`,
   `- threads with event evidence: ${result.context.threadsWithEvidence}`,
   `- event evidence snippets: ${result.context.evidenceItems}`,
@@ -153,15 +154,15 @@ const lines = [
   "",
   "Policy:",
   "- touched only `current_state.md` and `open_threads.md`",
-  "- used bounded cue-indexed event evidence for thread decisions",
-  "- did not modify append-only events or cue indexes",
-  "- moved historical detail out of wake-up context",
+  "- used bounded recent and thread evidence to update project memory",
+  "- did not modify append-only events or keyword indexes",
+  "- preserved supported lessons and remaining actions within the size budget",
 ];
 console.log(lines.join("\n"));
 NODE
 
   existing="$(gh pr list --repo "$LAGOON_REPOSITORY" --head "$branch" --state open --json number --jq '.[0].number // empty')"
-  title="Dream compact ${project} memory"
+  title="Dream update ${project} memory"
 
   if [[ -n "$existing" ]]; then
     gh api --method PATCH "repos/${LAGOON_REPOSITORY}/pulls/${existing}" \

package/docs/dream.md

@@ -2,16 +2,24 @@
 
 [← Back to README](../README.md)
 
-Dream is offline compaction for project wake-up context. It rewrites only:
+Dream keeps project wake-up context current and compact. It rewrites only:
 
 ```text
 projects/<project-slug>/current_state.md
 projects/<project-slug>/open_threads.md
 ```
 
-It does not dump event logs into the model prompt, does not rewrite append-only events, and does not run during normal MCP wake-up. When a project is over the threshold, Dream builds a capped thread evidence pack by searching cue-indexed project events for `open_threads.md` bullets. The evidence budget follows `--target-chars`, so the same size target controls both the desired output and the supporting context.
+Dream runs when a project has new indexed events or its wake-up context exceeds `--threshold-chars`. It does not run during normal MCP wake-up or modify append-only events.
 
-Dream uses an Eve-style compaction loop. It rewrites the complete curated snapshot, measures the result, and compacts that coherent result again when it is still over the target. It never crops a wake-up file. After three passes, it fails without writing either file if the snapshot still does not fit.
+Each run reads a chronological batch of up to 20 new indexed event excerpts, independent of existing open threads. The first run starts with the last seven days. After a successful write, a small `<!-- hippocamp-dream-through: ... -->` comment in `current_state.md` records the last event included. Preserve this comment when editing the file. Later runs resume there, including after downtime; events after the last included event wait for the next run. If the first excerpt alone exceeds the recent-event budget, Dream fails without writing and asks for a larger `--target-chars`. If the comment is removed, Dream starts again with the last seven days.
+
+Recent events use at most half of the evidence budget. The remaining budget supports searches for existing `open_threads.md` bullets. The total evidence budget follows `--target-chars`. The model receives bounded coherent excerpts with source paths and timestamps, never whole event logs or raw indexes.
+
+Dream promotes clear decisions, explicit corrections, and reusable project lessons into `current_state.md`, with source references. It keeps remaining actions in `open_threads.md`, preserves unresolved blockers, and removes completed actions only when evidence supports it. A merged PR does not prove its deployment or follow-up work is done. Uncertain lessons remain in events for normal search.
+
+Corrections apply across both files: a shipped feature should not remain an implementation task, while unverified deployment stays open. Extra compaction passes must keep source paths and timestamps for retained knowledge and aim below the size limit to leave room for length estimates. Dream writes the review comment itself; the model does not set review progress.
+
+The snapshot may grow within `--target-chars` when new evidence adds useful knowledge. If it exceeds the target, Dream compacts the complete result again. It never crops a wake-up file. After three passes, it fails without writing either file or advancing the event comment if the snapshot still does not fit. A project below the threshold with no new indexed evidence is skipped without a model call.
 
 Dry-run is the default:
 
@@ -26,7 +34,7 @@ npm run dream -- --project my-project --write
 - `MANIFEST_API_KEY`
 - `HIPPOCAMP_DREAM_MODEL` (defaults to `auto`; override if you want a specific provider/model)
 
-The GitHub Actions template at `assets/github-actions/hippocamp-dream.yml` is meant to be copied into the private Lagoon memory repo as `.github/workflows/hippocamp-dream.yml`. It runs on a schedule only, scans projects over the wake-up threshold, and creates or updates one PR per project. With `HIPPOCAMP_DREAM_AUTO_MERGE=true`, Dream squash-merges the PR only when the repository name is `lagoon` and the PR changes only the two curated project files.
+The GitHub Actions template at `assets/github-actions/hippocamp-dream.yml` is meant to be copied into the private Lagoon memory repo as `.github/workflows/hippocamp-dream.yml`. It runs on a schedule only, scans projects with new events or oversized wake-up context, and creates or updates one PR per project. With `HIPPOCAMP_DREAM_AUTO_MERGE=true`, Dream squash-merges the PR only when the repository name is `lagoon` and the PR changes only the two curated project files.
 
 ## Railway
 

package/docs/how-it-works.md

@@ -67,18 +67,18 @@ Typical agent flow:
 1. Call `wake_up` at the start of a top-level task.
 2. Read the returned global and project memory.
 3. Use `search_memory` for task-specific recall after wake-up.
-4. Use `append_event` for meaningful milestones, with a title and 1-8 concise cues.
+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`.
 
-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 cues above titles and titles above bodies. It returns small coherent evidence blocks from indexed events. If no indexed result is strong enough, it returns no event result instead of scanning whole event logs.
+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.
 
 ## Memory Rules
 
 - Keep memory concise.
 - Prefer curated summaries over raw event history.
-- Give events a short `Cues:` section; cues weigh the most in search ranking.
+- Give events a short `Keywords:` section; keywords weigh the most in search ranking. Older events with 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.
@@ -92,7 +92,7 @@ Example event content:
 Agent: claude
 Session: mcp-a1b2c3d4
 
-Cues:
+Keywords:
 - local-first
 - token-free
 - install-story

package/docs/setup.md

@@ -57,6 +57,7 @@ Environment variables are optional for local use:
 - `HIPPOCAMP_GLOBAL_ROOT`: local Lagoon clone path. Default: `~/.lagoon`
 - `HIPPOCAMP_PROJECT_ROOT`: project root used to infer the current project slug. Default: current working directory
 - Git worktrees, including Conductor workspaces, resolve to the main repository name so every workspace shares the same project memory.
+- An empty folder (nothing but `.git`, like a fresh agent session folder) has no project: project memory falls back to global memory, so these sessions start clean and stay searchable from everywhere.
 - `MANIFEST_BASE_URL`: OpenAI-compatible base URL used by `hippocamp dream --write`
 - `MANIFEST_API_KEY`: API key used by `hippocamp dream --write`
 - `HIPPOCAMP_DREAM_MODEL`: model used by Dream. Default: `auto`

package/package.json

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

package/scripts/eval-lagoon.cjs

@@ -61,8 +61,9 @@ async function run(options) {
   }
 
   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.
+  // searchMemory derives the project slug from the folder name, so a temp path per
+  // slug reads that project's memory without touching any real repo. The folder is
+  // not created: an existing empty folder has no project and reads global memory.
   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: [] };
@@ -74,7 +75,6 @@ async function run(options) {
       }
 
       const projectRoot = path.join(sandboxRoot, item.project);
-      await fs.mkdir(projectRoot, { recursive: true });
 
       const search = await memory.searchMemory({
         query: item.query,