hippocamp 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+HIPPOCAMP_GLOBAL_ROOT=~/.lagoon
+HIPPOCAMP_PROJECT_ROOT=
+HIPPOCAMP_DREAM_MODEL=auto
+HIPPOCAMP_DREAM_THRESHOLD_CHARS=20000
+HIPPOCAMP_DREAM_TARGET_CHARS=15000
+MANIFEST_BASE_URL=
+MANIFEST_API_KEY=

package/AGENTS.md

@@ -0,0 +1,74 @@
+# AGENTS.md
+
+This repository is a local-first MCP package for Git-backed agent memory. Keep changes narrow, explicit, and easy to verify.
+
+## Purpose
+
+- The product stores agent memory as Markdown files in a local Git repo, usually `~/.lagoon`.
+- The local Git repo syncs to a usually private GitHub remote through the user's normal Git credentials.
+- Git sync is intentional: it provides audit history, private cloud backup, and cross-machine or cross-agent continuity without a Hippocamp-specific database or token.
+- The app is intentionally not a database, notes app, queue, vector store, cloud API, or auth broker.
+- MVP primitives are:
+  - `events/`
+  - `projects/<slug>/`
+  - curated root Markdown files such as `identity.md` and `preferences.md`
+
+## Stack
+
+- Node.js CommonJS scripts
+- MCP stdio server
+- Local filesystem reads and writes
+- Git CLI for commit/push sync
+
+## Repository Map
+
+- `scripts/hippocamp.cjs`: small CLI wrapper for `dream`, `mcp`, `install-codex`, and `install-claude`.
+- `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/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.
+- `skills/hippocamp-memory/SKILL.md`: installable skill that tells agents how to use Hippocamp memory.
+- `assets/github-actions/hippocamp-dream.yml`: scheduled workflow template for Lagoon repos that opens one Dream PR per project.
+- `assets/brand/hippocamp-mascot.png`: README mascot asset.
+
+## Project Invariants
+
+- Memory paths must stay under the selected Lagoon memory root.
+- 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.
+- Curated files such as `current_state.md` and `open_threads.md` use explicit file writes.
+- Event entries should include concise `Cues:` values for fuzzy recall when possible.
+- 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.
+- The Dream GitHub Actions workflow is a Lagoon repo template. It should remain schedule-only and create reviewable PRs rather than pushing directly to `main`.
+
+## Change Rules
+
+- Follow the existing style and keep changes surgical.
+- Do not add abstractions, config knobs, or new subsystems unless the task explicitly requires them.
+- If behavior changes, update `README.md` and this file only when operational guidance actually changes.
+- Prefer extending `scripts/hippocamp-memory.cjs` over duplicating path, sync, or search logic.
+- Keep the product narrow. Simpler is better in this repo.
+
+## Verification
+
+When changing code, use the smallest verification that proves the change:
+
+- Run `node --check scripts/*.cjs` for script syntax changes.
+- 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.
+- There is no dedicated test suite yet, so do not claim test coverage that does not exist.
+
+## Notes For Future Agents
+
+- 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 CLI compaction, current/open curated files plus bounded thread evidence, one PR per project.
+- The local install story should stay: install MCP, point at Lagoon, rely on normal Git auth.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guillaume Gay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# Hippocamp
+
+<p align="center">
+  <img src="./assets/brand/hippocamp-mascot.png" alt="Hippocamp mascot" width="220" />
+</p>
+
+Hippocamp is local Git-backed memory for AI coding agents.
+
+Agents can edit large codebases, run tests, and push commits, but every new session still starts with amnesia. Project decisions, user preferences, open threads, and "why we did this" context get scattered across chat history, scratch notes, and PR comments. The result is repeated explanations, stale assumptions, and agents rediscovering the same facts instead of continuing the work.
+
+Hippocamp gives Codex, Claude Code, and other MCP clients a small shared memory surface they can wake up from, update, and sync. The memory is plain Markdown in a private Git repo you own.
+
+No database. No hosted memory service. No vector store. No separate token broker.
+
+## What It Stores
+
+- durable preferences and working style
+- current project state and open threads
+- meaningful events and decisions
+- references to commits, PRs, issues, reviews, and CI instead of duplicated GitHub facts
+
+## Why Git
+
+Git is a practical default for agent memory:
+
+- Auditable: every memory change has a diff, author, timestamp, and commit history.
+- Readable: memory stays as Markdown files that humans and agents can inspect without a special UI.
+- Collaborative: multiple agents and humans can review, branch, merge, and roll back the same memory repo.
+- Portable: a private remote lets the same memory follow you across machines and agent environments.
+- Agent-native: coding agents are already connected to GitHub through MCP, CLIs, or local Git credentials, so Hippocamp does not need an external database, hosted dependency, or separate token setup.
+
+## Install
+
+Clone this repo, install dependencies, then install the MCP server for your agent:
+
+```bash
+npm install
+npm run install:codex
+```
+
+For Claude Code:
+
+```bash
+npm install
+npm run install:claude
+```
+
+After publishing, the intended one-line install shape is:
+
+```bash
+npx hippocamp install-codex
+```
+
+Upgrade uses the same install path, so agents can refresh themselves without a separate state model:
+
+```bash
+npx hippocamp@latest upgrade-codex
+npx hippocamp@latest upgrade-claude
+```
+
+From a source checkout:
+
+```bash
+git pull --ff-only
+npm install
+npm run upgrade:codex
+npm run upgrade:claude
+```
+
+Both installers default to `~/.lagoon` as the memory repo. You can override it:
+
+```bash
+npm run install:codex -- --global-root /absolute/path/to/lagoon
+npm run install:claude -- --global-root /absolute/path/to/lagoon
+```
+
+The Codex installer refreshes `~/.codex/AGENTS.md`. The Claude installer refreshes `~/.claude/CLAUDE.md`.
+Both managed instruction blocks tell the agent to call `wake_up` at the start of new top-level coding tasks before repo exploration or edits.
+
+## Lagoon Repo
+
+Hippocamp expects a local Git repo for memory:
+
+```bash
+git clone git@github.com:YOUR_USER/lagoon.git ~/.lagoon
+```
+
+The repo should usually be private. Pushing memory to a private remote keeps it available across machines and agent environments while still using normal Git access controls. Hippocamp does not need a GitHub token for local MCP mode; it uses your normal local Git credentials.
+
+If push auth is not configured yet, use your preferred GitHub setup. With GitHub CLI:
+
+```bash
+gh auth login
+gh auth setup-git
+cd ~/.lagoon
+git push --dry-run
+```
+
+Once `git push --dry-run` works from `~/.lagoon`, Hippocamp can sync memory.
+
+## Memory Layout
+
+Global memory lives in:
+
+```text
+~/.lagoon/
+```
+
+Project memory lives in:
+
+```text
+~/.lagoon/projects/<project-slug>/
+```
+
+Suggested files:
+
+```text
+identity.md
+how_i_work.md
+preferences.md
+open_loops.md
+events/YYYY-MM-DD.md
+events/YYYY-MM-DD.index.json
+projects/<project-slug>/
+  project.md
+  current_state.md
+  open_threads.md
+  events/YYYY-MM-DD.md
+  events/YYYY-MM-DD.index.json
+```
+
+## MCP Tools
+
+The local MCP server exposes:
+
+- `wake_up`
+- `read_memory_file`
+- `write_memory_file`
+- `append_event`
+- `list_memory_files`
+- `search_memory`
+- `sync_memory`
+
+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` only when wake-up files are not enough.
+4. Use `append_event` for meaningful milestones, with concise cues when possible.
+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 keeps cue-based fuzzy search fast and rebuildable.
+
+## Dream
+
+Dream is offline compaction for project wake-up context. 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. This gives the model enough context to keep, rewrite, close, or promote threads without loading raw history.
+
+Dry-run is the default:
+
+```bash
+npm run dream -- --all --dry-run --json
+npm run dream -- --project my-project --write
+```
+
+`--write` requires a Manifest/OpenAI-compatible Responses API endpoint. The default environment variables are:
+
+- `MANIFEST_BASE_URL`
+- `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 so each memory compaction is reviewable.
+
+## Memory Rules
+
+- Keep memory concise.
+- Prefer curated summaries over raw event history.
+- Give events a short `Cues:` section so fuzzy search can recall them without scanning full bodies first.
+- 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.
+- Use global scope only for durable context that should follow you across projects.
+
+Example event content:
+
+```md
+Cues:
+- local-first
+- token-free
+- install-story
+
+References:
+- commit: abc1234
+- pr: #12
+
+Decision:
+Keep the local MCP path token-free and rely on normal git credentials.
+
+Why:
+This reduces onboarding friction for open-source users and avoids cloud auth concerns in the MVP.
+```
+
+## Commands
+
+```bash
+npm run mcp
+npm run mcp:help
+npm run mcp:smoke
+npm run dream
+npm run install:codex
+npm run install:claude
+npm run upgrade:codex
+npm run upgrade:claude
+```
+
+## Configuration
+
+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
+- `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`
+- `HIPPOCAMP_DREAM_THRESHOLD_CHARS`: wake-up size required before Dream proposes compaction. Default: `20000`
+- `HIPPOCAMP_DREAM_TARGET_CHARS`: target combined size for `current_state.md` and `open_threads.md`. Default: `15000`
+
+## What This Is Not
+
+- Not a hosted cloud service
+- Not a database
+- Not a notes app
+- Not a vector store
+- Not a queue
+
+The cloud/API version can be redesigned later. The MVP is intentionally local-first and Git-native.

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

@@ -0,0 +1,136 @@
+name: Hippocamp Dream
+
+on:
+  schedule:
+    - cron: "17 3 * * *"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: hippocamp-dream
+  cancel-in-progress: false
+
+jobs:
+  dream:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    env:
+      HIPPOCAMP_GLOBAL_ROOT: ${{ github.workspace }}
+      HIPPOCAMP_DREAM_THRESHOLD_CHARS: "20000"
+      HIPPOCAMP_DREAM_TARGET_CHARS: "15000"
+      HIPPOCAMP_DREAM_MODEL: ${{ secrets.HIPPOCAMP_DREAM_MODEL }}
+      MANIFEST_BASE_URL: ${{ secrets.MANIFEST_BASE_URL }}
+      MANIFEST_API_KEY: ${{ secrets.MANIFEST_API_KEY }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Configure git
+        run: |
+          git config user.name "hippocamp-dream[bot]"
+          git config user.email "hippocamp-dream[bot]@users.noreply.github.com"
+
+      - name: Find projects over threshold
+        run: |
+          npx -y hippocamp@latest dream \
+            --all \
+            --dry-run \
+            --json \
+            --threshold-chars "$HIPPOCAMP_DREAM_THRESHOLD_CHARS" \
+            > /tmp/hippocamp-dream-scan.json
+
+          node - <<'NODE'
+          const fs = require("node:fs");
+          const scan = JSON.parse(fs.readFileSync("/tmp/hippocamp-dream-scan.json", "utf8"));
+          const projects = scan.results
+            .filter((item) => item.skipped === "dry_run")
+            .map((item) => item.project);
+          fs.writeFileSync("/tmp/hippocamp-dream-projects.txt", `${projects.join("\n")}\n`);
+          console.log(`Dream candidates: ${projects.length ? projects.join(", ") : "none"}`);
+          NODE
+
+      - name: Create or update Dream PRs
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          while IFS= read -r project; do
+            [ -n "$project" ] || continue
+
+            branch="dream/${project}"
+            git fetch origin main
+            git checkout -B "$branch" origin/main
+
+            npx -y hippocamp@latest dream \
+              --project "$project" \
+              --write \
+              --json \
+              --threshold-chars "$HIPPOCAMP_DREAM_THRESHOLD_CHARS" \
+              --target-chars "$HIPPOCAMP_DREAM_TARGET_CHARS" \
+              > "/tmp/hippocamp-dream-${project}.json"
+
+            if git diff --quiet -- "projects/${project}/current_state.md" "projects/${project}/open_threads.md"; then
+              echo "No Dream diff for ${project}"
+              git checkout main
+              git reset --hard origin/main
+              continue
+            fi
+
+            git add "projects/${project}/current_state.md" "projects/${project}/open_threads.md"
+            git commit -m "Dream compact ${project} memory"
+            git push --force-with-lease origin "$branch"
+
+            node - "$project" "/tmp/hippocamp-dream-${project}.json" > "/tmp/hippocamp-dream-${project}.md" <<'NODE'
+            const fs = require("node:fs");
+            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.`,
+              "",
+              "Before:",
+              `- wake_up: ${result.wakeUpChars} chars`,
+              `- current_state.md: ${result.files["current_state.md"]} bytes`,
+              `- open_threads.md: ${result.files["open_threads.md"]} bytes`,
+              "",
+              "Context:",
+              `- open threads found: ${result.context.openThreads}`,
+              `- threads with event evidence: ${result.context.threadsWithEvidence}`,
+              `- event evidence snippets: ${result.context.evidenceItems}`,
+              `- evidence budget used: ${result.context.evidenceChars}/${result.context.evidenceBudgetChars} chars`,
+              "",
+              "After:",
+              `- wake_up: ${result.afterWakeUpChars} chars`,
+              `- current_state.md + open_threads.md: ${result.afterBytes} bytes`,
+              "",
+              "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",
+            ];
+            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"
+
+            if [ -n "$existing" ]; then
+              gh pr edit "$existing" --title "$title" --body-file "/tmp/hippocamp-dream-${project}.md"
+            else
+              gh pr create --title "$title" --body-file "/tmp/hippocamp-dream-${project}.md" --head "$branch" --base main
+            fi
+
+            git checkout main
+            git reset --hard origin/main
+          done < /tmp/hippocamp-dream-projects.txt

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "hippocamp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Local Git-backed memory for AI agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/guillaumegay13/hippocamp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guillaumegay13/hippocamp/issues"
+  },
+  "homepage": "https://github.com/guillaumegay13/hippocamp#readme",
+  "keywords": [
+    "agents",
+    "mcp",
+    "memory",
+    "markdown",
+    "git"
+  ],
+  "bin": {
+    "hippocamp": "scripts/hippocamp.cjs",
+    "hippocamp-dream": "scripts/hippocamp-dream.cjs",
+    "hippocamp-mcp": "scripts/hippocamp-mcp.cjs",
+    "hippocamp-install-codex": "scripts/install-codex.cjs",
+    "hippocamp-install-claude": "scripts/install-claude.cjs"
+  },
+  "scripts": {
+    "dream": "node scripts/hippocamp-dream.cjs",
+    "install:claude": "node scripts/install-claude.cjs",
+    "install:codex": "node scripts/install-codex.cjs",
+    "mcp": "node scripts/hippocamp-mcp.cjs",
+    "mcp:help": "node scripts/hippocamp-mcp.cjs --help",
+    "mcp:smoke": "node scripts/hippocamp-mcp.cjs --smoke",
+    "upgrade:claude": "node scripts/install-claude.cjs",
+    "upgrade:codex": "node scripts/install-codex.cjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  }
+}