hippocamp 0.2.6 → 0.2.8

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,
       });
     }
@@ -1215,6 +1226,49 @@ async function collectEventDocuments({ scope, eventFiles }) {
   };
 }
 
+// Dream reads a bounded chronological batch from indexes, then opens only the
+// referenced days. Unindexed logs are never used as a fallback.
+async function readRecentEvents({ projectRoot, after, before = new Date().toISOString(), maxResults = 20 }) {
+  const root = getScopeRoot("project", projectRoot);
+  const eventFiles = await listEventFiles(root);
+  const candidates = [];
+
+  for (const name of eventFiles.indexes) {
+    if (!/^\d{4}-\d{2}-\d{2}\.index\.json$/.test(name) || name.slice(0, 10) < after.slice(0, 10)) {
+      continue;
+    }
+    let index;
+    try {
+      index = await readJsonFileIfExists(path.join(eventFiles.eventsDir, name));
+    } catch {
+      continue;
+    }
+    for (const event of Array.isArray(index?.events) ? index.events : []) {
+      if (typeof event?.id === "string" && Number.isFinite(Date.parse(event.id)) && event.id > after && event.id <= before) {
+        candidates.push({ id: event.id, path: `events/${name.replace(/\.index\.json$/, ".md")}` });
+      }
+    }
+  }
+
+  candidates.sort((left, right) => left.id.localeCompare(right.id));
+  const days = new Map();
+  const results = [];
+  for (const candidate of candidates) {
+    if (results.length >= maxResults) break;
+    if (!days.has(candidate.path)) {
+      const target = resolveScopedPath("project", candidate.path, projectRoot);
+      const content = await readFileIfExists(target.absolutePath);
+      days.set(candidate.path, new Map(parseEventBlocks(content || "").map((block) => [block.id, block])));
+    }
+    const block = days.get(candidate.path).get(candidate.id);
+    if (!block) continue;
+    const snippet = createSearchExcerpt(block.body, createQueryInfo(block.heading || candidate.id));
+    if (!snippet) continue;
+    results.push({ ...candidate, heading: block.heading, snippet });
+  }
+  return results;
+}
+
 async function listCuratedMarkdownFiles(scope, root) {
   const markdownFiles = await walkMarkdownFiles(root);
 
@@ -1281,7 +1335,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 +1344,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 +1370,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 +1397,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 +1425,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 +1433,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 +1500,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 +1512,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 +1558,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 +1577,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}`,
   ];
 
@@ -1555,6 +1625,7 @@ module.exports = {
   appendEvent,
   listDirectoryEntries,
   searchMemory,
+  readRecentEvents,
   syncMemory,
   getDefaultSyncPaths,
   wakeUp,

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,9 +44,10 @@ 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.
+- Preserve any `<!-- hippocamp-dream-through: ... -->` comment in `current_state.md`; Dream uses it to avoid reviewing the same events again.
 - 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.