hippocamp 0.2.6 → 0.2.7

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 compaction sends `current_state.md`, `open_threads.md`, and bounded keyword-indexed event evidence for open-thread decisions. It must not dump full event logs, keyword indexes, or raw GitHub-owned facts into the model prompt.
 - 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.

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" />
@@ -30,6 +30,18 @@ A replay of a real session. Neither prompt mentions Hippocamp.
 - **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.

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

@@ -144,8 +144,8 @@ 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",
+            "- used bounded keyword-indexed event evidence for thread decisions",
+            "- did not modify append-only events or keyword indexes",
             "- moved historical detail out of wake-up context",
           ];
           console.log(lines.join("\n"));

package/assets/railway/run-dream.sh

@@ -153,8 +153,8 @@ 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",
+  "- used bounded keyword-indexed event evidence for thread decisions",
+  "- did not modify append-only events or keyword indexes",
   "- moved historical detail out of wake-up context",
 ];
 console.log(lines.join("\n"));

package/docs/dream.md

@@ -9,7 +9,7 @@ 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.
+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 keyword-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 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.
 

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.7",
   "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,

package/scripts/hippocamp-dream.cjs

@@ -272,7 +272,7 @@ async function buildThreadEvidence(report, { budgetChars }) {
     const item = {
       path: match.path,
       heading: match.heading,
-      cues: match.cues || [],
+      keywords: match.keywords || [],
       score: match.score,
       snippet: match.snippet,
     };
@@ -348,7 +348,7 @@ function createPrompt({ report, targetChars, threadEvidence }) {
         report.files["open_threads.md"].content.trim() || "# Open Threads",
         "",
         "## Thread Evidence",
-        "Evidence is retrieved from cue-indexed project events. It is intentionally small and may be incomplete.",
+        "Evidence is retrieved from keyword-indexed project events. It is intentionally small and may be incomplete.",
         `Evidence budget: ${threadEvidence.evidenceChars}/${threadEvidence.evidenceBudgetChars} chars`,
         JSON.stringify(threadEvidence.items, null, 2),
       ].join("\n"),

package/scripts/hippocamp-mcp.cjs

@@ -114,23 +114,23 @@ async function main() {
     "append_event",
     {
       description:
-        "Append a dated event entry under events/YYYY-MM-DD.md and update the sibling cue index. Requires a title and 1-8 short cues for recall. Automatically stamps Agent/Session provenance when available. Store references to GitHub artifacts instead of copying their content.",
+        "Append a dated event entry under events/YYYY-MM-DD.md and update the sibling keyword index. Requires a title and 1-8 short keywords for recall. Automatically stamps Agent/Session provenance when available. Store references to GitHub artifacts instead of copying their content.",
       inputSchema: {
         scope: z.enum(["global", "project"]).default("project"),
         title: z.string().trim().min(1),
-        cues: z.array(z.string().trim().min(1)).min(1).max(8),
+        keywords: z.array(z.string().trim().min(1)).min(1).max(8),
         content: z.string(),
         sync: z.boolean().optional(),
         projectRoot: projectRootSchema,
       },
     },
-    async ({ scope, title, cues, content, sync, projectRoot }) => {
+    async ({ scope, title, keywords, content, sync, projectRoot }) => {
       const clientVersion = server.server?.getClientVersion?.();
       return toTextResult(
         await memory.appendEvent({
           scope,
           title,
-          cues,
+          keywords,
           content,
           projectRoot,
           sync,
@@ -162,7 +162,7 @@ async function main() {
     "search_memory",
     {
       description:
-        "Search task-specific memory. Returns no results when the question's distinctive words appear in no memory, unless the question names a date. Event search uses cue indexes and returns only bounded coherent evidence; it does not scan unindexed event logs as a fallback. Event results carry their ISO timestamp as id; use it for when-questions. A month name in the query favors events from that month. A YYYY-MM-DD date, today, yesterday, this/last week, or this/last month keeps only events from those dates (UTC); undated files still match. Default 5 results suits a single fact; ask for 10-20 when the question combines several past sessions (counts, totals, comparisons, timelines), and search again if results look incomplete.",
+        "Search task-specific memory. Returns no results when the question's distinctive words appear in no memory, unless the question names a date. Event search uses keyword indexes and returns only bounded coherent evidence; it does not scan unindexed event logs as a fallback. Event results carry their ISO timestamp as id; use it for when-questions. A month name in the query favors events from that month. A YYYY-MM-DD date, today, yesterday, this/last week, or this/last month keeps only events from those dates (UTC); undated files still match. Default 5 results suits a single fact; ask for 10-20 when the question combines several past sessions (counts, totals, comparisons, timelines), and search again if results look incomplete.",
       inputSchema: {
         query: z.string(),
         scope: z.enum(["global", "project", "both"]).default("both"),

package/scripts/hippocamp-memory.cjs

@@ -24,7 +24,7 @@ const DEFAULT_PROJECT_FILES = [
 
 const EVENT_INDEX_VERSION = 1;
 const SEARCH_CANDIDATE_LIMIT = 60;
-const SEARCH_FIELD_BOOST = { cues: 3, heading: 2 };
+const SEARCH_FIELD_BOOST = { keywords: 3, heading: 2 };
 const SEARCH_FUZZY_DISTANCE = 0.2;
 const SEARCH_INDEX_CACHE_LIMIT = 8;
 const SEARCH_EXCERPT_MAX_CHARS = 1200;
@@ -148,10 +148,20 @@ function slugifyProjectName(value) {
   return slug || "project";
 }
 
+// An existing folder with nothing but .git (a fresh session or scratch folder) is not a project.
+function isEmptyFolder(folder) {
+  try {
+    return fsSync.readdirSync(folder).every((name) => name === ".git");
+  } catch {
+    return false;
+  }
+}
+
+// Null when the folder is empty: project memory then falls back to global memory.
 function getProjectSlug(projectRoot) {
   const resolvedProjectRoot = getProjectRoot(projectRoot);
-  const repositoryRoot = findRepositoryRootSync(resolvedProjectRoot);
-  return slugifyProjectName(path.basename(repositoryRoot || resolvedProjectRoot));
+  const folder = findRepositoryRootSync(resolvedProjectRoot) || resolvedProjectRoot;
+  return isEmptyFolder(folder) ? null : slugifyProjectName(path.basename(folder));
 }
 
 function getScopeRoot(scope, projectRoot) {
@@ -160,7 +170,8 @@ function getScopeRoot(scope, projectRoot) {
   }
 
   if (scope === "project") {
-    return path.join(getGlobalRoot(), "projects", getProjectSlug(projectRoot));
+    const slug = getProjectSlug(projectRoot);
+    return slug ? path.join(getGlobalRoot(), "projects", slug) : getGlobalRoot();
   }
 
   throw new Error(`Unsupported scope: ${scope}`);
@@ -259,34 +270,34 @@ function tokenizeSearchText(value) {
   return normalized ? normalized.split(/\s+/).filter(Boolean) : [];
 }
 
-function normalizeCue(value) {
+function normalizeKeyword(value) {
   return tokenizeSearchText(value).join("-");
 }
 
-function normalizeCueList(cues) {
-  const values = Array.isArray(cues) ? cues : [];
-  return [...new Set(values.map(normalizeCue).filter(Boolean))];
+function normalizeKeywordList(keywords) {
+  const values = Array.isArray(keywords) ? keywords : [];
+  return [...new Set(values.map(normalizeKeyword).filter(Boolean))];
 }
 
-function splitInlineCueValues(value) {
+function splitInlineKeywordValues(value) {
   return String(value || "")
     .split(",")
     .map((item) => item.trim())
     .filter(Boolean);
 }
 
-function hasCuesSection(content) {
-  return content.split(/\r?\n/).some((line) => /^Cues:\s*/i.test(line.trim()));
+function hasKeywordsSection(content) {
+  return content.split(/\r?\n/).some((line) => /^(?:Keywords|Cues):\s*/i.test(line.trim()));
 }
 
-function formatCuesSection(cues) {
-  const normalizedCues = normalizeCueList(cues);
+function formatKeywordsSection(keywords) {
+  const normalizedKeywords = normalizeKeywordList(keywords);
 
-  if (!normalizedCues.length) {
+  if (!normalizedKeywords.length) {
     return "";
   }
 
-  return ["Cues:", ...normalizedCues.map((cue) => `- ${cue}`)].join("\n");
+  return ["Keywords:", ...normalizedKeywords.map((keyword) => `- ${keyword}`)].join("\n");
 }
 
 function normalizeAgentName(value) {
@@ -313,7 +324,7 @@ function normalizeAgentName(value) {
     return AGENT_NAME_ALIASES[firstToken];
   }
 
-  const slug = normalizeCue(compact);
+  const slug = normalizeKeyword(compact);
 
   return slug || null;
 }
@@ -397,7 +408,7 @@ function extractAttributionFromEventLines(lines) {
       continue;
     }
 
-    // Provenance lines sit at the top of the body; stop at cues or free text.
+    // Provenance lines sit at the top of the body; stop at keywords or free text.
     break;
   }
 
@@ -654,7 +665,7 @@ function parseEventHeading(line) {
 
   if (!match) {
     return {
-      id: normalizeCue(heading) || heading,
+      id: normalizeKeyword(heading) || heading,
       heading,
     };
   }
@@ -665,22 +676,22 @@ function parseEventHeading(line) {
   };
 }
 
-function extractCuesFromEventLines(lines) {
+function extractKeywordsFromEventLines(lines) {
   for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].trim().match(/^Cues:\s*(.*)$/i);
+    const match = lines[index].trim().match(/^(?:Keywords|Cues):\s*(.*)$/i);
 
     if (!match) {
       continue;
     }
 
-    const cues = splitInlineCueValues(match[1]);
+    const keywords = splitInlineKeywordValues(match[1]);
 
     for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
       const line = lines[cursor];
       const bullet = line.match(/^\s*-\s+(.+?)\s*$/);
 
       if (bullet) {
-        cues.push(bullet[1]);
+        keywords.push(bullet[1]);
         continue;
       }
 
@@ -691,7 +702,7 @@ function extractCuesFromEventLines(lines) {
       break;
     }
 
-    return normalizeCueList(cues);
+    return normalizeKeywordList(keywords);
   }
 
   return [];
@@ -719,7 +730,7 @@ function parseEventBlocks(content) {
       heading: heading.heading,
       agent: attribution.agent,
       session: attribution.session,
-      cues: extractCuesFromEventLines(bodyLines),
+      keywords: extractKeywordsFromEventLines(bodyLines),
       content: blockLines.join("\n").trim(),
       body: bodyLines.join("\n").trim(),
       startLine: startIndex + 1,
@@ -735,7 +746,7 @@ function buildEventIndex(markdownContent, markdownPath) {
       const entry = {
         id: event.id,
         heading: event.heading,
-        cues: event.cues,
+        keywords: event.keywords,
       };
 
       if (event.agent) {
@@ -768,7 +779,7 @@ function createQueryInfo(query) {
   return {
     original,
     normalized: tokens.join(" "),
-    cue: tokens.join("-"),
+    keyword: tokens.join("-"),
     tokens,
     datePrefixes: queryDatePrefixes(original),
   };
@@ -847,7 +858,7 @@ function scoreSearchValues(queryInfo, values) {
   }
 
   const phraseScore = normalizedValues.reduce((bestScore, value) => {
-    if (value === queryInfo.normalized || value.replace(/\s+/g, "-") === queryInfo.cue) {
+    if (value === queryInfo.normalized || value.replace(/\s+/g, "-") === queryInfo.keyword) {
       return Math.max(bestScore, 1);
     }
 
@@ -919,7 +930,7 @@ function splitOversizedBlock(block) {
   return chunks;
 }
 
-function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
+function createSearchExcerpt(content, queryInfo) {
   const trimmed = content.trim();
 
   if (!trimmed) {
@@ -934,7 +945,7 @@ function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
     .split(/\n\s*\n+/)
     .map((block) => block.trim())
     .filter(Boolean)
-    .filter((block) => !/^(?:Agent:|Session:|Cues:)\s*/i.test(block))
+    .filter((block) => !/^(?:Agent:|Session:|Keywords:|Cues:)\s*/i.test(block))
     .flatMap(splitOversizedBlock);
 
   if (!blocks.length) {
@@ -956,8 +967,8 @@ function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
   // Keep the best-matching paragraphs that fit the excerpt budget, in file order.
   const hits = index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE }).map((hit) => hit.id);
 
-  // An event chosen by its date may share no words with the query; then lead with its first paragraphs.
-  for (const id of hits.length || !leadWhenUnmatched ? hits : blocks.map((_, position) => position)) {
+  // An event chosen by its date, keywords, or title may share no words with its paragraphs; then lead with the first ones.
+  for (const id of hits.length ? hits : blocks.map((_, position) => position)) {
     const added = blocks[id].length + (picked.length ? 2 : 0);
 
     if (length + added > SEARCH_EXCERPT_MAX_CHARS) {
@@ -988,7 +999,7 @@ async function writeMemoryFile({ scope, path: relativePath, content, projectRoot
   const target = resolveScopedPath(scope, relativePath, projectRoot);
 
   if (target.path === "events" || target.path.startsWith("events/")) {
-    throw new Error("events/ is append-only. Use append_event with a title and cues instead.");
+    throw new Error("events/ is append-only. Use append_event with a title and keywords instead.");
   }
 
   const nextContent = ensureTrailingNewline(requireNonEmptyString(content, "content"));
@@ -1055,7 +1066,7 @@ async function withEventFileLock(filePath, action) {
 async function appendEvent({
   scope = "project",
   content,
-  cues,
+  keywords,
   projectRoot,
   sync = true,
   title,
@@ -1067,13 +1078,13 @@ async function appendEvent({
 }) {
   const body = requireNonEmptyString(content, "content");
   const attribution = resolveWriteAttribution({ agent, session, clientName });
-  const normalizedCues = normalizeCueList(cues);
-  const cuedBody =
-    normalizedCues.length && !hasCuesSection(body)
-      ? `${formatCuesSection(normalizedCues)}\n\n${body.trim()}`
+  const normalizedKeywords = normalizeKeywordList(keywords);
+  const bodyWithKeywords =
+    normalizedKeywords.length && !hasKeywordsSection(body)
+      ? `${formatKeywordsSection(normalizedKeywords)}\n\n${body.trim()}`
       : body.trim();
   const attributionSection = formatAttributionSection(attribution);
-  const eventBody = attributionSection ? `${attributionSection}\n\n${cuedBody}` : cuedBody;
+  const eventBody = attributionSection ? `${attributionSection}\n\n${bodyWithKeywords}` : bodyWithKeywords;
   const relativePath = `events/${date}.md`;
   const target = resolveScopedPath(scope, relativePath, projectRoot);
 
@@ -1122,7 +1133,7 @@ async function appendEvent({
     title: title?.trim() || null,
     agent: parsed?.agent || attribution.agent,
     session: parsed?.session || attribution.session,
-    cues: parsed?.cues || [],
+    keywords: parsed?.keywords || [],
     indexPath,
     sync: syncResult,
   };
@@ -1203,7 +1214,7 @@ async function collectEventDocuments({ scope, eventFiles }) {
         path: `events/${markdownName}`,
         id: event.id,
         heading: event.heading,
-        cues: normalizeCueList(event.cues),
+        keywords: normalizeKeywordList(event.keywords || event.cues),
         body: block.body,
       });
     }
@@ -1281,7 +1292,7 @@ function queryDatePrefixes(query, now = new Date()) {
 
 function buildSearchIndex(documents) {
   const index = new MiniSearch({
-    fields: ["cues", "heading", "body", "date"],
+    fields: ["keywords", "heading", "body", "date"],
     idField: "position",
     tokenize: tokenizeSearchText,
     processTerm: (term) => term,
@@ -1290,7 +1301,7 @@ function buildSearchIndex(documents) {
   index.addAll(
     documents.map((document, position) => ({
       position,
-      cues: (document.cues || []).join(" "),
+      keywords: (document.keywords || []).join(" "),
       heading: document.heading || document.path,
       body: document.body,
       date: eventDateText(document.id),
@@ -1316,14 +1327,22 @@ function rankSearchDocuments(queryInfo, { index, documents }) {
     .map((hit) => ({
       document: documents[hit.id],
       score: Math.round(hit.score * 100) / 100,
-      queryTerms: hit.queryTerms,
+      terms: hit.terms,
     }));
 }
 
-// Share of the question's rare-word weight (IDF) that the best match contains. A question
-// whose rare words ("kubernetes", "namespace") appear in no memory gets a low share even when
-// common words ("backend", "deploy") match, so search can return nothing instead of noise.
-function rareWordCoverage(queryInfo, best, { index, documents }) {
+// Same word in another form: a plural or longer form ("deploy", "deployments") or the same stem
+// ("creating", "creation"). A typo-tolerant hit on a different word ("instinct", "instance",
+// "content", "context") is not.
+function sameWord(left, right) {
+  const stem = (word) => word.replace(/(?:ments?|ings?|ions?|ers?|ed|es|s)$/, "");
+  return tokenSimilarity(left, right) >= 0.9 || (stem(left).length >= 4 && stem(left) === stem(right));
+}
+
+// Share of the question's rare-word weight (IDF) that the best of the returned matches contains.
+// A question whose rare words ("kubernetes", "namespace") appear in no memory gets a low share even
+// when common words ("backend", "deploy") match, so search can return nothing instead of noise.
+function rareWordCoverage(queryInfo, candidates, { index, documents }) {
   // Month names only rank (see eventDateText); they say when, not what.
   const words = [
     ...new Set(
@@ -1335,15 +1354,19 @@ function rareWordCoverage(queryInfo, best, { index, documents }) {
     return 1;
   }
 
-  const weight = (word) => Math.log(1 + documents.length / (index.search(word, { fuzzy: 0 }).length + 0.5));
-  const matched = new Set(best?.queryTerms || []);
-  const total = words.reduce((sum, word) => sum + weight(word), 0);
+  const weights = new Map(
+    words.map((word) => [word, Math.log(1 + documents.length / (index.search(word, { fuzzy: 0 }).length + 0.5))]),
+  );
+  const total = words.reduce((sum, word) => sum + weights.get(word), 0);
+  const coverage = ({ terms }) =>
+    words.filter((word) => terms.some((term) => sameWord(word, term))).reduce((sum, word) => sum + weights.get(word), 0) /
+    total;
 
-  return words.filter((word) => matched.has(word)).reduce((sum, word) => sum + weight(word), 0) / total;
+  return Math.max(0, ...candidates.map(coverage));
 }
 
 function toSearchResult(queryInfo, { document, score }) {
-  const snippet = createSearchExcerpt(document.body, queryInfo, queryInfo.datePrefixes.length > 0);
+  const snippet = createSearchExcerpt(document.body, queryInfo);
 
   if (!snippet) {
     return null;
@@ -1359,7 +1382,7 @@ function toSearchResult(queryInfo, { document, score }) {
     };
   }
 
-  const cueScore = scoreSearchValues(queryInfo, document.cues);
+  const keywordScore = scoreSearchValues(queryInfo, document.keywords);
   const headingScore = scoreSearchValues(queryInfo, [document.heading || "", document.id]);
 
   return {
@@ -1367,9 +1390,9 @@ function toSearchResult(queryInfo, { document, score }) {
     path: document.path,
     id: document.id,
     heading: document.heading,
-    cues: document.cues,
+    keywords: document.keywords,
     score,
-    match: cueScore > 0 && cueScore >= headingScore ? "cues" : headingScore > 0 ? "heading" : "body",
+    match: keywordScore > 0 && keywordScore >= headingScore ? "keywords" : headingScore > 0 ? "heading" : "body",
     snippet,
   };
 }
@@ -1434,7 +1457,11 @@ async function loadSearchIndex(scopes, projectRoot) {
 async function searchMemory({ query, scope = "both", projectRoot, maxResults = 5 }) {
   const queryInfo = createQueryInfo(query);
   const clampedMaxResults = Math.max(1, Math.min(Number(maxResults) || 5, 20));
-  const scopes = scope === "both" ? ["global", "project"] : [scope];
+  const hasProject = getProjectSlug(projectRoot) !== null;
+  // Without a project, project scope is global memory; search it once, as global.
+  const scopes = [
+    ...new Set((scope === "both" ? ["global", "project"] : [scope]).map((name) => (name === "project" && !hasProject ? "global" : name))),
+  ];
   const search = await loadSearchIndex(scopes, projectRoot);
   const results = [];
 
@@ -1442,7 +1469,7 @@ async function searchMemory({ query, scope = "both", projectRoot, maxResults = 5
   // Dated questions skip the check: their date words describe time, not the topic.
   const related =
     queryInfo.datePrefixes.length > 0 ||
-    rareWordCoverage(queryInfo, candidates[0], search) >= SEARCH_MIN_RARE_WORD_COVERAGE;
+    rareWordCoverage(queryInfo, candidates.slice(0, clampedMaxResults), search) >= SEARCH_MIN_RARE_WORD_COVERAGE;
 
   if (related) {
     for (const candidate of candidates) {
@@ -1488,7 +1515,7 @@ async function wakeUp({ projectRoot } = {}) {
     });
   }
 
-  for (const relativePath of DEFAULT_PROJECT_FILES) {
+  for (const relativePath of projectSlug ? DEFAULT_PROJECT_FILES : []) {
     const file = await readMemoryFile({ scope: "project", path: relativePath, projectRoot });
 
     if (!file.found) {
@@ -1507,7 +1534,7 @@ async function wakeUp({ projectRoot } = {}) {
     "",
     `Global root: ${globalRoot}`,
     `Project root: ${resolvedProjectRoot}`,
-    `Project slug: ${projectSlug}`,
+    `Project slug: ${projectSlug || "none (empty folder; project memory is global memory)"}`,
     `Project memory root: ${projectMemoryRoot}`,
   ];
 

package/scripts/install-claude.cjs

@@ -113,7 +113,7 @@ function buildClaudeManagedBlock() {
     "- 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`.",
+    "- When appending events, pass a `title` and 1-8 concise `keywords` 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`.",

package/scripts/install-codex.cjs

@@ -121,7 +121,7 @@ function buildCodexManagedBlock() {
     "- 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`.",
+    "- When appending events, pass a `title` and 1-8 concise `keywords` 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`.",

package/scripts/install-grok.cjs

@@ -122,7 +122,7 @@ function buildGrokManagedBlock() {
     "- 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`.",
+    "- When appending events, pass a `title` and 1-8 concise `keywords` 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`.",

package/skills/hippocamp-memory/SKILL.md

@@ -17,7 +17,7 @@ Upgrade uses the same path: run `npm run upgrade:codex`, `npm run upgrade:claude
 
 - 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 current project slug is inferred from `HIPPOCAMP_PROJECT_ROOT` or the current working directory. An empty folder (nothing but `.git`) has no project and uses global memory.
 - The Hippocamp MCP server exposes the tools that read and write those locations.
 
 ## Default Workflow
@@ -28,7 +28,7 @@ Upgrade uses the same path: run `npm run upgrade:codex`, `npm run upgrade:claude
    Keep the default 5 results for a single fact. Pass `maxResults` 10-20 when the question combines several past sessions (counts, totals, comparisons, timelines), and search again if the results look incomplete.
 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`.
+6. When appending events, pass a `title` and 1-8 concise `keywords` 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:
@@ -44,7 +44,7 @@ Upgrade uses the same path: run `npm run upgrade:codex`, `npm run upgrade:claude
 - Prefer curated summaries over raw event history.
 - 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.
+- Use event keywords as short recall handles; `search_memory` ranks indexed events by keywords, title, and body with typo tolerance, and keywords 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.

package/test/mcp-params.test.cjs

@@ -41,26 +41,26 @@ test("MCP server rejects calls that would succeed but misbehave", async (t) => {
   assert.equal(eventWrite.isError, true);
   assert.match(resultText(eventWrite), /append-only/);
 
-  const noCues = await client.callTool({
+  const noKeywords = await client.callTool({
     name: "append_event",
-    arguments: { title: "Missing cues", content: "Unsearchable.", sync: false },
+    arguments: { title: "Missing keywords", content: "Unsearchable.", sync: false },
   });
-  assert.equal(noCues.isError, true);
+  assert.equal(noKeywords.isError, true);
 
-  const tooManyCues = await client.callTool({
+  const tooManyKeywords = await client.callTool({
     name: "append_event",
     arguments: {
-      title: "Too many cues",
-      cues: Array.from({ length: 9 }, (_, index) => `cue-${index}`),
+      title: "Too many keywords",
+      keywords: Array.from({ length: 9 }, (_, index) => `keyword-${index}`),
       content: "Too broad.",
       sync: false,
     },
   });
-  assert.equal(tooManyCues.isError, true);
+  assert.equal(tooManyKeywords.isError, true);
 
   const noTitle = await client.callTool({
     name: "append_event",
-    arguments: { title: " ", cues: ["untitled"], content: "No heading.", sync: false },
+    arguments: { title: " ", keywords: ["untitled"], content: "No heading.", sync: false },
   });
   assert.equal(noTitle.isError, true);
 
@@ -73,8 +73,8 @@ test("MCP server rejects calls that would succeed but misbehave", async (t) => {
 
   const valid = await client.callTool({
     name: "append_event",
-    arguments: { title: "Valid event", cues: ["valid-cue"], content: "Indexed.", projectRoot, sync: false },
+    arguments: { title: "Valid event", keywords: ["valid-keyword"], content: "Indexed.", projectRoot, sync: false },
   });
   assert.notEqual(valid.isError, true);
-  assert.deepEqual(JSON.parse(resultText(valid)).cues, ["valid-cue"]);
+  assert.deepEqual(JSON.parse(resultText(valid)).keywords, ["valid-keyword"]);
 });

package/test/memory-efficiency.test.cjs

@@ -76,7 +76,6 @@ test("search uses indexed events and returns coherent evidence", async (t) => {
   const projectRoot = path.join(tempRoot, "search-project");
 
   process.env.HIPPOCAMP_GLOBAL_ROOT = lagoonRoot;
-  await fs.mkdir(projectRoot, { recursive: true });
   t.after(async () => {
     if (originalRoot === undefined) {
       delete process.env.HIPPOCAMP_GLOBAL_ROOT;
@@ -88,7 +87,7 @@ test("search uses indexed events and returns coherent evidence", async (t) => {
 
   await memory.appendEvent({
     content: "Decision:\nUse indexed search only.",
-    cues: ["strict-index"],
+    keywords: ["strict-index"],
     date: "2026-09-21",
     projectRoot,
     scope: "project",
@@ -109,7 +108,7 @@ test("search uses indexed events and returns coherent evidence", async (t) => {
 
   await memory.appendEvent({
     content: `Decision:\n${"x".repeat(1300)}`,
-    cues: ["oversized-metadata"],
+    keywords: ["oversized-metadata"],
     date: "2026-09-21",
     projectRoot,
     scope: "project",
@@ -124,7 +123,9 @@ test("search uses indexed events and returns coherent evidence", async (t) => {
     scope: "project",
   });
 
-  assert.deepEqual(oversized.results, []);
+  // A keyword-only match still returns whole paragraphs; the oversized run is left out, never cropped.
+  assert.equal(oversized.results[0]?.heading, "Large metadata-only match");
+  assert.equal(oversized.results[0].snippet, "Decision:");
 
   const projectMemoryRoot = path.join(lagoonRoot, "projects", "search-project");
   await fs.writeFile(
@@ -145,7 +146,7 @@ test("search uses indexed events and returns coherent evidence", async (t) => {
   const eventsRoot = path.join(projectMemoryRoot, "events");
   await fs.writeFile(
     path.join(eventsRoot, "2026-09-20.md"),
-    "# Events: 2026-09-20\n\n## 09:00 — Hidden fallback\n\nCues:\n- quasar-velvet\n\nShould not be scanned.\n",
+    "# Events: 2026-09-20\n\n## 09:00 — Hidden fallback\n\nKeywords:\n- quasar-velvet\n\nShould not be scanned.\n",
     "utf8",
   );
 
@@ -174,11 +175,11 @@ test("search ranks indexed event bodies with typo tolerance", async (t) => {
     await fs.rm(tempRoot, { recursive: true, force: true });
   });
 
-  for (const [title, cues, content] of [
+  for (const [title, keywords, content] of [
     ["Deploy note", ["deploy"], "The zanzibar migration needs a rollback plan."],
     ["Unrelated note", ["billing"], "Invoices are generated monthly."],
   ]) {
-    await memory.appendEvent({ content, cues, projectRoot, scope: "project", sync: false, title });
+    await memory.appendEvent({ content, keywords, projectRoot, scope: "project", sync: false, title });
   }
 
   const search = await memory.searchMemory({ projectRoot, query: "zanzibr rollback", scope: "project" });
@@ -188,6 +189,42 @@ test("search ranks indexed event bodies with typo tolerance", async (t) => {
   assert.equal(search.results[0].match, "body");
 });
 
+test("search still matches events written with legacy Cues sections and indexes", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-legacy-cues-"));
+  const projectRoot = path.join(tempRoot, "legacy-project");
+  const eventsRoot = path.join(tempRoot, "lagoon", "projects", "legacy-project", "events");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(eventsRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const id = "2026-09-01T09:00:00.000Z";
+  await fs.writeFile(
+    path.join(eventsRoot, "2026-09-01.md"),
+    `# Events — 2026-09-01\n\n## ${id} — Old note\n\nCues:\n- quasar-velvet\n\nOld body.\n`,
+    "utf8",
+  );
+  await fs.writeFile(
+    path.join(eventsRoot, "2026-09-01.index.json"),
+    JSON.stringify({ version: 1, path: "2026-09-01.md", events: [{ id, heading: "Old note", cues: ["quasar-velvet"] }] }),
+    "utf8",
+  );
+
+  const search = await memory.searchMemory({ projectRoot, query: "quasar velvet", scope: "project" });
+
+  assert.equal(search.results.length, 1);
+  assert.deepEqual(search.results[0].keywords, ["quasar-velvet"]);
+  assert.equal(search.results[0].match, "keywords");
+});
+
 test("search returns whole sentences from an oversized matching paragraph", async (t) => {
   const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-long-paragraph-"));
@@ -207,7 +244,7 @@ test("search returns whole sentences from an oversized matching paragraph", asyn
   const filler = "The weekly sync covered routine updates. ".repeat(40);
   await memory.appendEvent({
     content: `${filler}The kestrel database moved to eu-west-3. ${filler}`,
-    cues: ["infra"],
+    keywords: ["infra"],
     projectRoot,
     scope: "project",
     sync: false,
@@ -246,7 +283,7 @@ test("search returns every matching paragraph that fits the excerpt budget", asy
   ];
   await memory.appendEvent({
     content: paragraphs.join("\n\n"),
-    cues: ["infra"],
+    keywords: ["infra"],
     projectRoot,
     scope: "project",
     sync: false,
@@ -282,7 +319,7 @@ test("events appended in the same millisecond keep distinct ids and bodies", asy
   const timestamp = "2026-10-01T09:00:00.000Z";
   const first = await memory.appendEvent({
     content: "The zanzibar migration needs a rollback plan.",
-    cues: ["deploy"],
+    keywords: ["deploy"],
     projectRoot,
     scope: "project",
     sync: false,
@@ -291,7 +328,7 @@ test("events appended in the same millisecond keep distinct ids and bodies", asy
   });
   const second = await memory.appendEvent({
     content: "Invoices are generated monthly.",
-    cues: ["billing"],
+    keywords: ["billing"],
     projectRoot,
     scope: "project",
     sync: false,
@@ -329,7 +366,7 @@ test("parallel appends keep every event", async (t) => {
     Array.from({ length: 20 }, (_, index) =>
       memory.appendEvent({
         content: `Parallel event ${index}.`,
-        cues: ["parallel"],
+        keywords: ["parallel"],
         date: "2026-10-01",
         projectRoot,
         scope: "project",
@@ -366,7 +403,7 @@ test("search favors events from a month named in the query", async (t) => {
   for (const timestamp of ["2026-05-02T08:00:00.000Z", "2026-08-05T10:00:00.000Z", "2026-09-01T09:00:00.000Z"]) {
     await memory.appendEvent({
       content: "Published the Android build to Google Play production.",
-      cues: ["android-release"],
+      keywords: ["android-release"],
       date: timestamp.slice(0, 10),
       projectRoot,
       scope: "project",
@@ -407,7 +444,7 @@ test("search favors events from a relative date named in the query", async (t) =
     await memory.appendEvent({
       // The old event matches the words better, so only the date words can rank the others first.
       content: key === "older" ? "Deploy key rotation: rotated the deploy key again." : "Rotated the key for staging.",
-      cues: ["deploy-key"],
+      keywords: ["deploy-key"],
       date: timestamp.slice(0, 10),
       projectRoot,
       scope: "project",
@@ -448,7 +485,7 @@ test("search returns a snippet for a long event matched only by its date", async
 
   await memory.appendEvent({
     content: Array(30).fill("The weekly sync covered routine updates.").join("\n\n"),
-    cues: ["sync"],
+    keywords: ["sync"],
     date: "2026-08-05",
     projectRoot,
     scope: "project",
@@ -485,7 +522,7 @@ test("search returns nothing when no memory is about the question", async (t) =>
     ["Deploy rollback", "A failed backend deploy rolls back to the previous revision."],
     ["Billing note", "Invoices are generated monthly."],
   ]) {
-    await memory.appendEvent({ content, cues: ["ops"], projectRoot, scope: "project", sync: false, title });
+    await memory.appendEvent({ content, keywords: ["ops"], projectRoot, scope: "project", sync: false, title });
   }
 
   const unrelated = await memory.searchMemory({ projectRoot, query: "which kubernetes namespace does the backend deploy to", scope: "project" });
@@ -498,3 +535,130 @@ test("search returns nothing when no memory is about the question", async (t) =>
   // No event is from August; the month name must not count as a missing topic word.
   assert.ok(monthOnly.results.length > 0);
 });
+
+test("search keeps an event matched only by a keyword its long body never repeats", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-keyword-only-"));
+  const projectRoot = path.join(tempRoot, "keyword-only-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const content = [
+    "Opened three hardening PRs after the security audit.",
+    "The backend PR rotates the cron secret and checks request signatures on every scheduled job. ".repeat(8),
+    "The website PR updates the content studio dependencies and removes an unused preview route. ".repeat(8),
+  ].join("\n\n");
+
+  assert.ok(content.length > 1200);
+  await memory.appendEvent({
+    content,
+    keywords: ["security-audit", "strava-oauth"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    title: "Security audit opened hardening PRs",
+  });
+
+  const search = await memory.searchMemory({ projectRoot, query: "Strava bug", scope: "project" });
+
+  assert.equal(search.results[0]?.heading, "Security audit opened hardening PRs");
+  assert.match(search.results[0].snippet, /^Opened three hardening PRs/);
+});
+
+test("search returns nothing when a rare word only resembles memory words", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-lookalike-"));
+  const projectRoot = path.join(tempRoot, "lookalike-project");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = path.join(tempRoot, "lagoon");
+  await fs.mkdir(projectRoot, { recursive: true });
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  await memory.appendEvent({
+    content: "Each worker instance reads the instruct prompt and its content before a sync.",
+    keywords: ["health-sync"],
+    projectRoot,
+    scope: "project",
+    sync: false,
+    title: "Apple Health sync banner hardening",
+  });
+
+  // "instinct" is one typo away from "instance" and "instruct" but means something else.
+  const lookalike = await memory.searchMemory({ projectRoot, query: "Instinct", scope: "project" });
+  const shared = await memory.searchMemory({ projectRoot, query: "context", scope: "project" });
+  const plural = await memory.searchMemory({ projectRoot, query: "worker instances", scope: "project" });
+
+  assert.deepEqual(lookalike.results, []);
+  assert.deepEqual(shared.results, []);
+  assert.equal(plural.results[0]?.heading, "Apple Health sync banner hardening");
+});
+
+test("an empty folder has no project and uses global memory", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-empty-folder-"));
+  const lagoonRoot = path.join(tempRoot, "lagoon");
+  const emptyRoot = path.join(tempRoot, "billowy-glove");
+  const codeRoot = path.join(tempRoot, "job-search");
+
+  process.env.HIPPOCAMP_GLOBAL_ROOT = lagoonRoot;
+  // Only .git, like a fresh session folder some agents create.
+  await fs.mkdir(path.join(emptyRoot, ".git"), { recursive: true });
+  await fs.mkdir(codeRoot, { recursive: true });
+  await fs.writeFile(path.join(codeRoot, "notes.md"), "Job search notes.\n", "utf8");
+  t.after(async () => {
+    if (originalRoot === undefined) {
+      delete process.env.HIPPOCAMP_GLOBAL_ROOT;
+    } else {
+      process.env.HIPPOCAMP_GLOBAL_ROOT = originalRoot;
+    }
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  });
+
+  const wake = await memory.wakeUp({ projectRoot: emptyRoot });
+  const event = await memory.appendEvent({
+    content: "Created the applying-to-jobs skill.",
+    keywords: ["applying-to-jobs"],
+    projectRoot: emptyRoot,
+    scope: "project",
+    sync: false,
+    title: "Job application skill created",
+  });
+  await memory.appendEvent({
+    content: "Created the applying-to-jobs tracker in Notion.",
+    keywords: ["applying-to-jobs-tracker"],
+    projectRoot: codeRoot,
+    scope: "project",
+    sync: false,
+    title: "Job tracker created",
+  });
+  const fromEmpty = await memory.searchMemory({ projectRoot: emptyRoot, query: "applying to jobs skill" });
+  const projectScope = await memory.searchMemory({ projectRoot: emptyRoot, query: "applying to jobs", scope: "project" });
+  const fromProject = await memory.searchMemory({ projectRoot: codeRoot, query: "applying to jobs skill" });
+
+  assert.equal(wake.projectSlug, null);
+  assert.equal(wake.projectMemoryRoot, lagoonRoot);
+  assert.equal(path.dirname(path.dirname(event.indexPath)), lagoonRoot);
+  // Global memory is searched once, and other projects stay out of it.
+  assert.deepEqual(fromEmpty.results.map((result) => result.heading), ["Job application skill created"]);
+  assert.deepEqual(projectScope.results.map((result) => result.heading), ["Job application skill created"]);
+  assert.equal(fromProject.results[0]?.heading, "Job application skill created");
+  assert.equal(memory.getProjectSlug(codeRoot), "job-search");
+  // A folder that does not exist keeps its name, as Dream's synthetic roots do.
+  assert.equal(memory.getProjectSlug(path.join(tempRoot, "missing")), "missing");
+});

package/test/sync-memory.test.cjs

@@ -29,7 +29,6 @@ test("sync commits when the Lagoon path goes through a symlink", async (t) => {
   });
 
   await fs.mkdir(realLagoon);
-  await fs.mkdir(projectRoot);
   await fs.symlink(realLagoon, linkedLagoon);
   git(["init", "-q", "-b", "main"]);
   git(["commit", "-q", "--allow-empty", "-m", "init"]);
@@ -45,7 +44,7 @@ test("sync commits when the Lagoon path goes through a symlink", async (t) => {
 
   const result = await memory.appendEvent({
     content: "Use advisory locks.",
-    cues: ["locks"],
+    keywords: ["locks"],
     projectRoot,
     scope: "project",
     title: "Queue decision",
@@ -56,12 +55,11 @@ test("sync commits when the Lagoon path goes through a symlink", async (t) => {
 
   // A symlink inside the Lagoon pointing at another project must not be synced as this one.
   const otherProject = path.join(tempRoot, "other-project");
-  await fs.mkdir(otherProject);
   await fs.mkdir(path.join(realLagoon, "projects", "other-project"), { recursive: true });
   await fs.symlink(path.join(realLagoon, "projects", "linked-project", "events"), path.join(realLagoon, "projects", "other-project", "events"));
 
   await assert.rejects(
-    memory.appendEvent({ content: "Cross write.", cues: ["x"], projectRoot: otherProject, scope: "project", title: "Escape" }),
+    memory.appendEvent({ content: "Cross write.", keywords: ["x"], projectRoot: otherProject, scope: "project", title: "Escape" }),
     /escapes the memory root/,
   );
 });