hippocamp 0.1.0

package/scripts/hippocamp.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+
+const COMMANDS = {
+  dream: "hippocamp-dream.cjs",
+  mcp: "hippocamp-mcp.cjs",
+  "install-codex": "install-codex.cjs",
+  "install-claude": "install-claude.cjs",
+  "upgrade-codex": "install-codex.cjs",
+  "upgrade-claude": "install-claude.cjs",
+};
+
+function printHelp() {
+  console.log(`Hippocamp
+
+Usage:
+  hippocamp dream
+  hippocamp mcp
+  hippocamp install-codex
+  hippocamp install-claude
+  hippocamp upgrade-codex
+  hippocamp upgrade-claude
+
+Commands:
+  dream           Run offline Dream memory compaction
+  mcp             Run the local MCP server
+  install-codex   Install the Hippocamp skill and MCP server into Codex
+  install-claude  Install the Hippocamp skill and MCP server into Claude Code
+  upgrade-codex   Upgrade the Codex Hippocamp install
+  upgrade-claude  Upgrade the Claude Code Hippocamp install
+`);
+}
+
+function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const script = COMMANDS[command];
+
+  if (!script) {
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+  }
+
+  const child = spawn(process.execPath, [path.join(__dirname, script), ...args], {
+    stdio: "inherit",
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code || 0);
+  });
+}
+
+main();

package/scripts/install-claude.cjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { execFile } = require("node:child_process");
+const { promisify } = require("node:util");
+
+const execFileAsync = promisify(execFile);
+
+const CLAUDE_MANAGED_START = "<!-- hippocamp:managed:start -->";
+const CLAUDE_MANAGED_END = "<!-- hippocamp:managed:end -->";
+const HIPPOCAMP_SKILL_NAME = "hippocamp-memory";
+
+function expandHomePath(value) {
+  if (!value) {
+    return value;
+  }
+
+  if (value === "~") {
+    return os.homedir();
+  }
+
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function parseArgs(argv) {
+  const options = {
+    claudeHome: expandHomePath("~/.claude"),
+    globalRoot: expandHomePath(process.env.HIPPOCAMP_GLOBAL_ROOT || "~/.lagoon"),
+    serverName: "hippocamp",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--claude-home") {
+      options.claudeHome = path.resolve(expandHomePath(argv[index + 1]));
+      index += 1;
+      continue;
+    }
+
+    if (token === "--global-root") {
+      options.globalRoot = path.resolve(expandHomePath(argv[index + 1]));
+      index += 1;
+      continue;
+    }
+
+    if (token === "--server-name") {
+      options.serverName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`Install Hippocamp into Claude Code.
+
+Usage:
+  node scripts/install-claude.cjs [--claude-home PATH] [--global-root PATH] [--server-name NAME]
+
+Defaults:
+  --claude-home  ~/.claude
+  --global-root  ~/.lagoon
+  --server-name  hippocamp
+`);
+}
+
+async function runClaude(args) {
+  try {
+    const result = await execFileAsync("claude", args);
+    return {
+      ok: true,
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: error.stdout?.trim() || "",
+      stderr: error.stderr?.trim() || error.message,
+    };
+  }
+}
+
+function buildClaudeManagedBlock() {
+  return [
+    CLAUDE_MANAGED_START,
+    "# Hippocamp",
+    "",
+    "- For every new top-level coding task, call the Hippocamp `wake_up` MCP tool before inspecting repository files, planning, or editing.",
+    "- Read the returned global and project memory before using other memory tools.",
+    "- Do this even when the user does not explicitly mention memory.",
+    "- Only call `search_memory` if the wake-up files are insufficient.",
+    "- If `wake_up` is unavailable or fails, say so explicitly and continue without memory instead of silently skipping it.",
+    "- After meaningful code or content changes, checkpoint project memory before the final response.",
+    "- When project state changes, use `append_event` for milestones and update curated files such as `current_state.md` and `open_threads.md` before finishing the task.",
+    "- When appending events, include concise `Cues:` values or pass the `cues` argument so fuzzy recall can find the event later.",
+    "- Do not duplicate commits, PRs, issues, reviews, or CI results in memory; store references plus the missing rationale, preference, assumption, or follow-up context.",
+    "- If a project-memory write does not sync automatically, call `sync_memory` before finishing the task.",
+    "- If the user asks to upgrade Hippocamp for Claude Code, run `npx hippocamp@latest upgrade-claude`; from a source checkout, run `git pull --ff-only`, `npm install`, then `npm run upgrade:claude`.",
+    "- Before writing, reviewing, or refactoring code, read and follow `/Users/guillaumegay/.agents/skills/karpathy-guidelines/SKILL.md` unless the user explicitly asks to skip it.",
+    CLAUDE_MANAGED_END,
+    "",
+  ].join("\n");
+}
+
+function upsertManagedBlock(existingContent, block) {
+  if (!existingContent) {
+    return block;
+  }
+
+  const startIndex = existingContent.indexOf(CLAUDE_MANAGED_START);
+  const endIndex = existingContent.indexOf(CLAUDE_MANAGED_END);
+
+  if (startIndex >= 0 && endIndex >= 0 && endIndex >= startIndex) {
+    const before = existingContent.slice(0, startIndex).trimEnd();
+    const after = existingContent.slice(endIndex + CLAUDE_MANAGED_END.length).trimStart();
+    return [before, block.trimEnd(), after].filter(Boolean).join("\n\n").concat("\n");
+  }
+
+  return `${existingContent.trimEnd()}\n\n${block}`;
+}
+
+async function ensureClaudeInstructionsInstalled({ claudeHome }) {
+  const claudeMdPath = path.join(claudeHome, "CLAUDE.md");
+  const existingContent = await fs.readFile(claudeMdPath, "utf8").catch((error) => {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return "";
+    }
+
+    throw error;
+  });
+  const nextContent = upsertManagedBlock(existingContent, buildClaudeManagedBlock());
+
+  await fs.mkdir(claudeHome, { recursive: true });
+  await fs.writeFile(claudeMdPath, nextContent, "utf8");
+
+  return claudeMdPath;
+}
+
+async function copyDirectory(sourceDir, targetDir) {
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  await fs.mkdir(targetDir, { recursive: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await fs.copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+async function ensureClaudeSkillInstalled({ claudeHome, repoRoot }) {
+  const sourceDir = path.join(repoRoot, "skills", HIPPOCAMP_SKILL_NAME);
+  const skillsDir = path.join(claudeHome, "skills");
+  const targetDir = path.join(skillsDir, HIPPOCAMP_SKILL_NAME);
+  const legacyAgentPath = path.join(claudeHome, "agents", `${HIPPOCAMP_SKILL_NAME}.md`);
+
+  await copyDirectory(sourceDir, targetDir);
+  await fs.rm(legacyAgentPath, { force: true }).catch((error) => {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return;
+    }
+
+    throw error;
+  });
+
+  return targetDir;
+}
+
+async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
+  const existing = await runClaude(["mcp", "get", serverName]);
+
+  if (existing.ok) {
+    const removed = await runClaude(["mcp", "remove", "--scope", "user", serverName]);
+
+    if (!removed.ok) {
+      throw new Error(removed.stderr || `Failed to remove existing MCP server: ${serverName}`);
+    }
+  }
+
+  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const added = await runClaude([
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "stdio",
+    serverName,
+    "--env",
+    `HIPPOCAMP_GLOBAL_ROOT=${globalRoot}`,
+    "--",
+    process.execPath,
+    scriptPath,
+  ]);
+
+  if (!added.ok) {
+    throw new Error(added.stderr || `Failed to add MCP server: ${serverName}`);
+  }
+
+  return {
+    name: serverName,
+    command: process.execPath,
+    scriptPath,
+    globalRoot,
+    summary: added.stdout || added.stderr,
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const repoRoot = path.resolve(__dirname, "..");
+
+  await fs.mkdir(options.claudeHome, { recursive: true });
+
+  const claudeMdPath = await ensureClaudeInstructionsInstalled({
+    claudeHome: options.claudeHome,
+  });
+  const claudeSkillPath = await ensureClaudeSkillInstalled({
+    claudeHome: options.claudeHome,
+    repoRoot,
+  });
+
+  const server = await ensureServerInstalled({
+    repoRoot,
+    globalRoot: options.globalRoot,
+    serverName: options.serverName,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        claudeHome: options.claudeHome,
+        claudeMdPath,
+        claudeSkillPath,
+        server,
+        note: "Restart Claude Code to load the installed MCP server, Hippocamp skill, and refreshed CLAUDE.md instructions.",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+main().catch((error) => {
+  console.error("Failed to install Hippocamp into Claude Code:", error.message);
+  process.exit(1);
+});

package/scripts/install-codex.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const { execFile } = require("node:child_process");
+const { promisify } = require("node:util");
+
+const execFileAsync = promisify(execFile);
+const CODEX_MANAGED_START = "<!-- hippocamp:managed:start -->";
+const CODEX_MANAGED_END = "<!-- hippocamp:managed:end -->";
+
+function expandHomePath(value) {
+  if (!value) {
+    return value;
+  }
+
+  if (value === "~") {
+    return os.homedir();
+  }
+
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function parseArgs(argv) {
+  const options = {
+    codexHome: expandHomePath(process.env.CODEX_HOME || "~/.codex"),
+    globalRoot: expandHomePath(process.env.HIPPOCAMP_GLOBAL_ROOT || "~/.lagoon"),
+    serverName: "hippocamp",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--codex-home") {
+      options.codexHome = path.resolve(expandHomePath(argv[index + 1]));
+      index += 1;
+      continue;
+    }
+
+    if (token === "--global-root") {
+      options.globalRoot = path.resolve(expandHomePath(argv[index + 1]));
+      index += 1;
+      continue;
+    }
+
+    if (token === "--server-name") {
+      options.serverName = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`Install Hippocamp into Codex.
+
+Usage:
+  node scripts/install-codex.cjs [--codex-home PATH] [--global-root PATH] [--server-name NAME]
+
+Defaults:
+  --codex-home   ~/.codex
+  --global-root  ~/.lagoon
+  --server-name  hippocamp
+`);
+}
+
+async function runCodex(args) {
+  try {
+    const result = await execFileAsync("codex", args);
+    return {
+      ok: true,
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: error.stdout?.trim() || "",
+      stderr: error.stderr?.trim() || error.message,
+    };
+  }
+}
+
+async function ensureSkillInstalled({ repoRoot, codexHome }) {
+  const sourceDir = path.join(repoRoot, "skills", "hippocamp-memory");
+  const targetDir = path.join(codexHome, "skills", "hippocamp-memory");
+
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.copyFile(path.join(sourceDir, "SKILL.md"), path.join(targetDir, "SKILL.md"));
+
+  return targetDir;
+}
+
+function buildCodexManagedBlock() {
+  return [
+    CODEX_MANAGED_START,
+    "# Hippocamp",
+    "",
+    "- For every new top-level coding task, call the Hippocamp `wake_up` MCP tool before inspecting repository files, planning, or editing.",
+    "- Read the returned global and project memory before using other memory tools.",
+    "- Do this even when the user does not explicitly mention memory.",
+    "- Only call `search_memory` if the wake-up files are insufficient.",
+    "- If `wake_up` is unavailable or fails, say so explicitly and continue without memory instead of silently skipping it.",
+    "- After meaningful code or content changes, checkpoint project memory before the final response.",
+    "- When project state changes, use `append_event` for milestones and update curated files such as `current_state.md` and `open_threads.md` before finishing the task.",
+    "- When appending events, include concise `Cues:` values or pass the `cues` argument so fuzzy recall can find the event later.",
+    "- Do not duplicate commits, PRs, issues, reviews, or CI results in memory; store references plus the missing rationale, preference, assumption, or follow-up context.",
+    "- If a project-memory write does not sync automatically, call `sync_memory` before finishing the task.",
+    "- If the user asks to upgrade Hippocamp for Codex, run `npx hippocamp@latest upgrade-codex`; from a source checkout, run `git pull --ff-only`, `npm install`, then `npm run upgrade:codex`.",
+    CODEX_MANAGED_END,
+    "",
+  ].join("\n");
+}
+
+function upsertManagedBlock(existingContent, block) {
+  if (!existingContent) {
+    return block;
+  }
+
+  const startIndex = existingContent.indexOf(CODEX_MANAGED_START);
+  const endIndex = existingContent.indexOf(CODEX_MANAGED_END);
+
+  if (startIndex >= 0 && endIndex >= 0 && endIndex >= startIndex) {
+    const before = existingContent.slice(0, startIndex).trimEnd();
+    const after = existingContent.slice(endIndex + CODEX_MANAGED_END.length).trimStart();
+    return [before, block.trimEnd(), after].filter(Boolean).join("\n\n").concat("\n");
+  }
+
+  return `${existingContent.trimEnd()}\n\n${block}`;
+}
+
+async function ensureCodexInstructionsInstalled({ codexHome }) {
+  const agentsMdPath = path.join(codexHome, "AGENTS.md");
+  const existingContent = await fs.readFile(agentsMdPath, "utf8").catch((error) => {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return "";
+    }
+
+    throw error;
+  });
+  const nextContent = upsertManagedBlock(existingContent, buildCodexManagedBlock());
+
+  await fs.mkdir(codexHome, { recursive: true });
+  await fs.writeFile(agentsMdPath, nextContent, "utf8");
+
+  return agentsMdPath;
+}
+
+async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
+  const existing = await runCodex(["mcp", "get", serverName, "--json"]);
+
+  if (existing.ok) {
+    const removed = await runCodex(["mcp", "remove", serverName]);
+
+    if (!removed.ok) {
+      throw new Error(removed.stderr || `Failed to remove existing MCP server: ${serverName}`);
+    }
+  }
+
+  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const added = await runCodex([
+    "mcp",
+    "add",
+    serverName,
+    "--env",
+    `HIPPOCAMP_GLOBAL_ROOT=${globalRoot}`,
+    "--",
+    process.execPath,
+    scriptPath,
+  ]);
+
+  if (!added.ok) {
+    throw new Error(added.stderr || `Failed to add MCP server: ${serverName}`);
+  }
+
+  return {
+    name: serverName,
+    command: process.execPath,
+    scriptPath,
+    globalRoot,
+    summary: added.stdout || added.stderr,
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const repoRoot = path.resolve(__dirname, "..");
+
+  await fs.mkdir(options.codexHome, { recursive: true });
+
+  const skillPath = await ensureSkillInstalled({
+    repoRoot,
+    codexHome: options.codexHome,
+  });
+  const codexInstructionsPath = await ensureCodexInstructionsInstalled({
+    codexHome: options.codexHome,
+  });
+
+  const server = await ensureServerInstalled({
+    repoRoot,
+    globalRoot: options.globalRoot,
+    serverName: options.serverName,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        codexHome: options.codexHome,
+        skillPath,
+        codexInstructionsPath,
+        server,
+        note: "Restart Codex to load the installed skill, MCP server, and refreshed AGENTS.md instructions.",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+main().catch((error) => {
+  console.error("Failed to install Hippocamp into Codex:", error.message);
+  process.exit(1);
+});

package/skills/hippocamp-memory/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hippocamp-memory
+description: Use Hippocamp memory to load global identity and workflow context from the Lagoon clone and project context from the Lagoon projects folder. Trigger this at the start of top-level task threads, when you need durable memory recall, or when you need to checkpoint meaningful progress.
+---
+
+# Hippocamp Memory
+
+Use this skill when the user wants persistent memory across agent sessions.
+
+This same skill can be installed into Codex or Claude Code.
+For Codex, use `npm run install:codex`; that installer copies this skill into `~/.codex/skills/hippocamp-memory/`, registers the Hippocamp MCP server, and refreshes `~/.codex/AGENTS.md`.
+For Claude Code, use `npm run install:claude`; that installer copies this skill into `~/.claude/skills/hippocamp-memory/`, registers the Hippocamp MCP server, and refreshes `~/.claude/CLAUDE.md`.
+Upgrade uses the same path: run `npm run upgrade:codex` or `npm run upgrade:claude` from a source checkout, or `npx hippocamp@latest upgrade-codex` / `npx hippocamp@latest upgrade-claude` after publishing.
+
+## Scope
+
+- Global memory lives at the root of the local Lagoon clone pointed to by `HIPPOCAMP_GLOBAL_ROOT`.
+- Project memory lives under `projects/<slug>/` inside that same Lagoon clone.
+- The current project slug is inferred from `HIPPOCAMP_PROJECT_ROOT` or the current working directory.
+- The Hippocamp MCP server exposes the tools that read and write those locations.
+
+## Default Workflow
+
+1. At the start of every top-level coding task, call `wake_up` before inspecting files, planning, or editing.
+2. Read the wake-up output before searching.
+3. Only call `search_memory` if the wake-up files are insufficient.
+4. During work, use `append_event` only for meaningful milestones.
+5. When appending events, include concise `Cues:` values or pass the `cues` argument so fuzzy recall can find the event later.
+6. `write_memory_file` and `append_event` sync by default.
+7. If a sync is skipped or fails, call `sync_memory` explicitly.
+8. At the end of the task, use `write_memory_file` to update curated files such as:
+   - `current_state.md`
+   - `open_threads.md`
+   - `identity.md`
+   - `how_i_work.md`
+   - `preferences.md`
+
+## Behavior Rules
+
+- Do not full-scan memory on every thread.
+- Prefer curated summaries over raw event history.
+- Use event cues as short recall handles; `search_memory` fuzzy-ranks cues and headings before reading matching event bodies.
+- Keep curated files short and legible.
+- 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 personal context that should follow the user across projects.
+- Avoid rewriting unrelated memory files.
+- Treat `sync_memory` as the recovery path when default sync cannot safely proceed.
+
+## Suggested Files
+
+Global:
+
+- `identity.md`
+- `how_i_work.md`
+- `preferences.md`
+- `open_loops.md`
+
+Project:
+
+- `project.md`
+- `current_state.md`
+- `open_threads.md`
+- `events/YYYY-MM-DD.md`
+- `events/YYYY-MM-DD.index.json`
+
+## Tooling
+
+Expected MCP tools:
+
+- `wake_up`
+- `read_memory_file`
+- `write_memory_file`
+- `append_event`
+- `list_memory_files`
+- `search_memory`
+- `sync_memory`