hippocamp 0.1.0 → 0.2.0

package/scripts/hippocamp.cjs

@@ -8,8 +8,10 @@ const COMMANDS = {
   mcp: "hippocamp-mcp.cjs",
   "install-codex": "install-codex.cjs",
   "install-claude": "install-claude.cjs",
+  "install-grok": "install-grok.cjs",
   "upgrade-codex": "install-codex.cjs",
   "upgrade-claude": "install-claude.cjs",
+  "upgrade-grok": "install-grok.cjs",
 };
 
 function printHelp() {
@@ -20,16 +22,20 @@ Usage:
   hippocamp mcp
   hippocamp install-codex
   hippocamp install-claude
+  hippocamp install-grok
   hippocamp upgrade-codex
   hippocamp upgrade-claude
+  hippocamp upgrade-grok
 
 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
+  install-grok    Install the Hippocamp skill and MCP server into Grok Build
   upgrade-codex   Upgrade the Codex Hippocamp install
   upgrade-claude  Upgrade the Claude Code Hippocamp install
+  upgrade-grok    Upgrade the Grok Build Hippocamp install
 `);
 }
 

package/scripts/install-claude.cjs

@@ -105,11 +105,14 @@ function buildClaudeManagedBlock() {
     "- 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.",
+    "- Use `search_memory` as the normal path for task-specific recall after wake-up.",
+    "- If `search_memory` returns no result, continue without memory instead of reading whole event logs as a fallback.",
     "- 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 re-read `current_state.md` or `open_threads.md` after `wake_up`; they are already loaded.",
+    "- Update curated files only when project state actually changed. For small tasks, `append_event` is enough.",
+    "- When appending events, pass a `title` and 1-8 concise `cues` so fuzzy recall can find the event later. Never write under `events/` with `write_memory_file`.",
     "- 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`.",
@@ -213,6 +216,8 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     serverName,
     "--env",
     `HIPPOCAMP_GLOBAL_ROOT=${globalRoot}`,
+    "--env",
+    "HIPPOCAMP_AGENT=claude",
     "--",
     process.execPath,
     scriptPath,

package/scripts/install-codex.cjs

@@ -113,11 +113,14 @@ function buildCodexManagedBlock() {
     "- 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.",
+    "- Use `search_memory` as the normal path for task-specific recall after wake-up.",
+    "- If `search_memory` returns no result, continue without memory instead of reading whole event logs as a fallback.",
     "- 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 re-read `current_state.md` or `open_threads.md` after `wake_up`; they are already loaded.",
+    "- Update curated files only when project state actually changed. For small tasks, `append_event` is enough.",
+    "- When appending events, pass a `title` and 1-8 concise `cues` so fuzzy recall can find the event later. Never write under `events/` with `write_memory_file`.",
     "- 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`.",
@@ -178,6 +181,8 @@ async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
     serverName,
     "--env",
     `HIPPOCAMP_GLOBAL_ROOT=${globalRoot}`,
+    "--env",
+    "HIPPOCAMP_AGENT=codex",
     "--",
     process.execPath,
     scriptPath,

package/scripts/install-grok.cjs

@@ -0,0 +1,260 @@
+#!/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 GROK_MANAGED_START = "<!-- hippocamp:managed:start -->";
+const GROK_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 = {
+    grokHome: expandHomePath(process.env.GROK_HOME || "~/.grok"),
+    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 === "--grok-home") {
+      options.grokHome = 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 Grok Build.
+
+Usage:
+  node scripts/install-grok.cjs [--grok-home PATH] [--global-root PATH] [--server-name NAME]
+
+Defaults:
+  --grok-home    ~/.grok
+  --global-root  ~/.lagoon
+  --server-name  hippocamp
+`);
+}
+
+async function runGrok(args) {
+  try {
+    const result = await execFileAsync("grok", 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, grokHome }) {
+  const sourceDir = path.join(repoRoot, "skills", HIPPOCAMP_SKILL_NAME);
+  const targetDir = path.join(grokHome, "skills", HIPPOCAMP_SKILL_NAME);
+
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.copyFile(path.join(sourceDir, "SKILL.md"), path.join(targetDir, "SKILL.md"));
+
+  return targetDir;
+}
+
+function buildGrokManagedBlock() {
+  return [
+    GROK_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.",
+    "- Use `search_memory` as the normal path for task-specific recall after wake-up.",
+    "- If `search_memory` returns no result, continue without memory instead of reading whole event logs as a fallback.",
+    "- 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.",
+    "- Do not re-read `current_state.md` or `open_threads.md` after `wake_up`; they are already loaded.",
+    "- Update curated files only when project state actually changed. For small tasks, `append_event` is enough.",
+    "- When appending events, pass a `title` and 1-8 concise `cues` so fuzzy recall can find the event later. Never write under `events/` with `write_memory_file`.",
+    "- 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 Grok Build, run `npx hippocamp@latest upgrade-grok`; from a source checkout, run `git pull --ff-only`, `npm install`, then `npm run upgrade:grok`.",
+    GROK_MANAGED_END,
+    "",
+  ].join("\n");
+}
+
+function upsertManagedBlock(existingContent, block) {
+  if (!existingContent) {
+    return block;
+  }
+
+  const startIndex = existingContent.indexOf(GROK_MANAGED_START);
+  const endIndex = existingContent.indexOf(GROK_MANAGED_END);
+
+  if (startIndex >= 0 && endIndex >= 0 && endIndex >= startIndex) {
+    const before = existingContent.slice(0, startIndex).trimEnd();
+    const after = existingContent.slice(endIndex + GROK_MANAGED_END.length).trimStart();
+    return [before, block.trimEnd(), after].filter(Boolean).join("\n\n").concat("\n");
+  }
+
+  return `${existingContent.trimEnd()}\n\n${block}`;
+}
+
+async function ensureGrokInstructionsInstalled({ grokHome }) {
+  const rulesDir = path.join(grokHome, "rules");
+  const rulesPath = path.join(rulesDir, "hippocamp.md");
+  const existingContent = await fs.readFile(rulesPath, "utf8").catch((error) => {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return "";
+    }
+
+    throw error;
+  });
+  const nextContent = upsertManagedBlock(existingContent, buildGrokManagedBlock());
+
+  await fs.mkdir(rulesDir, { recursive: true });
+  await fs.writeFile(rulesPath, nextContent, "utf8");
+
+  return rulesPath;
+}
+
+async function ensureServerInstalled({ repoRoot, globalRoot, serverName }) {
+  const existing = await runGrok(["mcp", "list"]);
+
+  if (!existing.ok && /not found|command not found|ENOENT/i.test(existing.stderr)) {
+    throw new Error(
+      existing.stderr ||
+        "grok CLI not found. Install Grok Build and ensure `grok` is on PATH, then retry.",
+    );
+  }
+
+  const listed = `${existing.stdout}\n${existing.stderr}`;
+  const hasServer =
+    existing.ok &&
+    listed
+      .split(/\r?\n/)
+      .some((line) => line.trim().startsWith(`${serverName}:`) || line.trim() === serverName);
+
+  if (hasServer) {
+    const removed = await runGrok(["mcp", "remove", serverName]);
+
+    if (!removed.ok && !/no mcp server named/i.test(removed.stderr || "")) {
+      throw new Error(removed.stderr || `Failed to remove existing MCP server: ${serverName}`);
+    }
+  }
+
+  const scriptPath = path.join(repoRoot, "scripts", "hippocamp-mcp.cjs");
+  const added = await runGrok([
+    "mcp",
+    "add",
+    serverName,
+    "-e",
+    `HIPPOCAMP_GLOBAL_ROOT=${globalRoot}`,
+    "-e",
+    "HIPPOCAMP_AGENT=grok",
+    "--",
+    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,
+    agent: "grok",
+    summary: added.stdout || added.stderr,
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const repoRoot = path.resolve(__dirname, "..");
+
+  await fs.mkdir(options.grokHome, { recursive: true });
+
+  const skillPath = await ensureSkillInstalled({
+    repoRoot,
+    grokHome: options.grokHome,
+  });
+  const grokInstructionsPath = await ensureGrokInstructionsInstalled({
+    grokHome: options.grokHome,
+  });
+
+  const server = await ensureServerInstalled({
+    repoRoot,
+    globalRoot: options.globalRoot,
+    serverName: options.serverName,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        grokHome: options.grokHome,
+        skillPath,
+        grokInstructionsPath,
+        server,
+        note: "Restart Grok Build (or start a new session) to load the installed skill, MCP server, and home rules.",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+main().catch((error) => {
+  console.error("Failed to install Hippocamp into Grok Build:", error.message);
+  process.exit(1);
+});

package/skills/hippocamp-memory/SKILL.md

@@ -7,10 +7,11 @@ description: Use Hippocamp memory to load global identity and workflow context f
 
 Use this skill when the user wants persistent memory across agent sessions.
 
-This same skill can be installed into Codex or Claude Code.
+This same skill can be installed into Codex, Claude Code, or Grok Build.
 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.
+For Grok Build, use `npm run install:grok`; that installer copies this skill into `~/.grok/skills/hippocamp-memory/`, registers the Hippocamp MCP server with `HIPPOCAMP_AGENT=grok`, and refreshes `~/.grok/rules/hippocamp.md`.
+Upgrade uses the same path: run `npm run upgrade:codex`, `npm run upgrade:claude`, or `npm run upgrade:grok` from a source checkout, or `npx hippocamp@latest upgrade-codex` / `upgrade-claude` / `upgrade-grok` after publishing.
 
 ## Scope
 
@@ -23,12 +24,13 @@ Upgrade uses the same path: run `npm run upgrade:codex` or `npm run upgrade:clau
 
 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:
+3. Use `search_memory` as the normal path for task-specific recall after wake-up.
+4. If search returns no result, continue without memory. Do not read whole event logs as a fallback.
+5. During work, use `append_event` only for meaningful milestones.
+6. When appending events, pass a `title` and 1-8 concise `cues` so fuzzy recall can find the event later. Never write under `events/` with `write_memory_file`.
+7. `write_memory_file` and `append_event` sync by default.
+8. If a sync is skipped or fails, call `sync_memory` explicitly.
+9. At the end of the task, if project state actually changed, use `write_memory_file` to update curated files such as:
    - `current_state.md`
    - `open_threads.md`
    - `identity.md`
@@ -39,8 +41,13 @@ Upgrade uses the same path: run `npm run upgrade:codex` or `npm run upgrade:clau
 
 - 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.
+- Do not re-read `current_state.md` or `open_threads.md` after `wake_up`; they are already loaded.
+- For small tasks, `append_event` is enough; skip curated file rewrites.
+- Use event cues as short recall handles; `search_memory` ranks indexed events by cues, title, and body with typo tolerance, and cues weigh the most.
+- Search returns bounded coherent evidence and does not scan unindexed event logs as a fallback.
 - Keep curated files short and legible.
+- Rewrite `current_state.md` as a short snapshot of what is true now. Do not prepend dated entries to it; milestone detail belongs in `append_event` only.
+- Remove resolved items from `open_threads.md` instead of keeping them.
 - 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.

package/test/mcp-params.test.cjs

@@ -0,0 +1,80 @@
+const assert = require("node:assert/strict");
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs/promises");
+const os = require("node:os");
+const path = require("node:path");
+const test = require("node:test");
+
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
+
+function resultText(result) {
+  return result.content.map((item) => item.text).join("\n");
+}
+
+test("MCP server rejects calls that would succeed but misbehave", async (t) => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-mcp-params-"));
+  const lagoonRoot = path.join(tempRoot, "lagoon");
+  const projectRoot = path.join(tempRoot, "params-project");
+
+  await fs.mkdir(projectRoot, { recursive: true });
+  execFileSync("git", ["init", "-q", projectRoot]);
+
+  const client = new Client({ name: "hippocamp-test", version: "0.0.0" });
+  await client.connect(
+    new StdioClientTransport({
+      command: process.execPath,
+      args: [path.join(__dirname, "..", "scripts", "hippocamp-mcp.cjs")],
+      cwd: projectRoot,
+      env: { ...process.env, HIPPOCAMP_GLOBAL_ROOT: lagoonRoot, HIPPOCAMP_PROJECT_ROOT: projectRoot },
+    }),
+  );
+  t.after(async () => {
+    await client.close();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const eventWrite = await client.callTool({
+    name: "write_memory_file",
+    arguments: { scope: "project", path: "events/2026-09-29.md", content: "## Bypass\n\nNo index.", sync: false },
+  });
+  assert.equal(eventWrite.isError, true);
+  assert.match(resultText(eventWrite), /append-only/);
+
+  const noCues = await client.callTool({
+    name: "append_event",
+    arguments: { title: "Missing cues", content: "Unsearchable.", sync: false },
+  });
+  assert.equal(noCues.isError, true);
+
+  const tooManyCues = await client.callTool({
+    name: "append_event",
+    arguments: {
+      title: "Too many cues",
+      cues: Array.from({ length: 9 }, (_, index) => `cue-${index}`),
+      content: "Too broad.",
+      sync: false,
+    },
+  });
+  assert.equal(tooManyCues.isError, true);
+
+  const noTitle = await client.callTool({
+    name: "append_event",
+    arguments: { title: " ", cues: ["untitled"], content: "No heading.", sync: false },
+  });
+  assert.equal(noTitle.isError, true);
+
+  const wrongProject = await client.callTool({
+    name: "wake_up",
+    arguments: { projectRoot: path.join(tempRoot, "missing-project") },
+  });
+  assert.equal(wrongProject.isError, true);
+  assert.match(resultText(wrongProject), /Git repository/);
+
+  const valid = await client.callTool({
+    name: "append_event",
+    arguments: { title: "Valid event", cues: ["valid-cue"], content: "Indexed.", projectRoot, sync: false },
+  });
+  assert.notEqual(valid.isError, true);
+  assert.deepEqual(JSON.parse(resultText(valid)).cues, ["valid-cue"]);
+});