hippocamp 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippocamp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "description": "Local Git-backed memory for AI agents.",
   "license": "MIT",

package/scripts/hippocamp-mcp.cjs

@@ -162,7 +162,7 @@ async function main() {
     "search_memory",
     {
       description:
-        "Search task-specific memory. 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.",
+        "Search task-specific memory. 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.",
       inputSchema: {
         query: z.string(),
         scope: z.enum(["global", "project", "both"]).default("both"),

package/scripts/hippocamp-memory.cjs

@@ -747,6 +747,7 @@ function createQueryInfo(query) {
     normalized: tokens.join(" "),
     cue: tokens.join("-"),
     tokens,
+    datePrefixes: queryDatePrefixes(original),
   };
 }
 
@@ -895,7 +896,7 @@ function splitOversizedBlock(block) {
   return chunks;
 }
 
-function createSearchExcerpt(content, queryInfo) {
+function createSearchExcerpt(content, queryInfo, leadWhenUnmatched = false) {
   const trimmed = content.trim();
 
   if (!trimmed) {
@@ -930,14 +931,17 @@ function createSearchExcerpt(content, queryInfo) {
   let length = 0;
 
   // Keep the best-matching paragraphs that fit the excerpt budget, in file order.
-  for (const hit of index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE })) {
-    const added = blocks[hit.id].length + (picked.length ? 2 : 0);
+  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)) {
+    const added = blocks[id].length + (picked.length ? 2 : 0);
 
     if (length + added > SEARCH_EXCERPT_MAX_CHARS) {
       continue;
     }
 
-    picked.push(hit.id);
+    picked.push(id);
     length += added;
   }
 
@@ -1214,9 +1218,47 @@ async function collectMarkdownDocuments({ scope, root, curatedFiles }) {
   };
 }
 
+const MONTH_NAMES = "january february march april may june july august september october november december".split(" ");
+
+// Search word for a UTC day ("2026-08-05" -> "d20260805") or month ("2026-08" -> "august").
+// A day is one exact word, so it never matches a neighbor day by typo tolerance.
+function dateTerm(prefix) {
+  return prefix.length === 10 ? `d${prefix.replace(/-/g, "")}` : MONTH_NAMES[Number(prefix.slice(5, 7)) - 1];
+}
+
+// Month and day words of an event's timestamp id.
+function eventDateText(id) {
+  return /^\d{4}-\d{2}-\d{2}T/.test(id || "") ? `${dateTerm(id.slice(0, 7))} ${dateTerm(id.slice(0, 10))}` : "";
+}
+
+// Dates a query asks for: YYYY-MM-DD dates and relative phrases, as UTC day
+// ("2026-08-05") or month ("2026-08") prefixes of event ids. Weeks start on Monday.
+function queryDatePrefixes(query, now = new Date()) {
+  const text = query.toLowerCase();
+  const prefixes = [...text.matchAll(/\b\d{4}-\d{2}-\d{2}\b/g)].map((match) => match[0]);
+  const utc = (months, days) =>
+    new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + months, days)).toISOString();
+  const addDays = (from, to) => {
+    for (let offset = from; offset <= to; offset += 1) {
+      prefixes.push(utc(0, now.getUTCDate() + offset).slice(0, 10));
+    }
+  };
+  const addMonth = (offset) => prefixes.push(utc(offset, 1).slice(0, 7));
+  const monday = -((now.getUTCDay() + 6) % 7);
+
+  if (/\btoday\b/.test(text)) addDays(0, 0);
+  if (/\byesterday\b/.test(text)) addDays(-1, -1);
+  if (/\bthis week\b/.test(text)) addDays(monday, 0);
+  if (/\blast week\b/.test(text)) addDays(monday - 7, monday - 1);
+  if (/\bthis month\b/.test(text)) addMonth(0);
+  if (/\blast month\b/.test(text)) addMonth(-1);
+
+  return prefixes;
+}
+
 function buildSearchIndex(documents) {
   const index = new MiniSearch({
-    fields: ["cues", "heading", "body"],
+    fields: ["cues", "heading", "body", "date"],
     idField: "position",
     tokenize: tokenizeSearchText,
     processTerm: (term) => term,
@@ -1228,6 +1270,7 @@ function buildSearchIndex(documents) {
       cues: (document.cues || []).join(" "),
       heading: document.heading || document.path,
       body: document.body,
+      date: eventDateText(document.id),
     })),
   );
 
@@ -1235,10 +1278,16 @@ function buildSearchIndex(documents) {
 }
 
 function rankSearchDocuments(queryInfo, { index, documents }) {
+  const { datePrefixes } = queryInfo;
+
+  // A date the query asks for filters events to those dates. Undated files always pass.
   return index
-    .search(queryInfo.normalized, {
+    .search([queryInfo.normalized, ...datePrefixes.map(dateTerm)].join(" "), {
       boost: SEARCH_FIELD_BOOST,
-      fuzzy: SEARCH_FUZZY_DISTANCE,
+      fuzzy: (term) => (/^d\d{8}$/.test(term) ? 0 : SEARCH_FUZZY_DISTANCE),
+      filter: datePrefixes.length
+        ? (hit) => !documents[hit.id].id || datePrefixes.some((prefix) => documents[hit.id].id.startsWith(prefix))
+        : undefined,
     })
     .slice(0, SEARCH_CANDIDATE_LIMIT)
     .map((hit) => ({
@@ -1248,7 +1297,7 @@ function rankSearchDocuments(queryInfo, { index, documents }) {
 }
 
 function toSearchResult(queryInfo, { document, score }) {
-  const snippet = createSearchExcerpt(document.body, queryInfo);
+  const snippet = createSearchExcerpt(document.body, queryInfo, queryInfo.datePrefixes.length > 0);
 
   if (!snippet) {
     return null;

package/test/memory-efficiency.test.cjs

@@ -346,3 +346,120 @@ test("parallel appends keep every event", async (t) => {
   assert.equal(new Set(ids).size, 20);
   assert.equal(new Set(results.map((result) => result.timestamp)).size, 20);
 });
+
+test("search favors events from a month named in the query", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-month-search-"));
+  const projectRoot = path.join(tempRoot, "month-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 });
+  });
+
+  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"],
+      date: timestamp.slice(0, 10),
+      projectRoot,
+      scope: "project",
+      sync: false,
+      timestamp,
+      title: "Android release",
+    });
+  }
+
+  const byMonth = await memory.searchMemory({ projectRoot, query: "android build in august", scope: "project" });
+  const byDay = await memory.searchMemory({ projectRoot, query: "android build 2026-05-02", scope: "project" });
+
+  assert.equal(byMonth.results[0].id, "2026-08-05T10:00:00.000Z");
+  assert.equal(byDay.results[0].id, "2026-05-02T08:00:00.000Z");
+});
+
+test("search favors events from a relative date named in the query", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-relative-date-"));
+  const projectRoot = path.join(tempRoot, "relative-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 });
+  });
+
+  // Seven days ago is always in last calendar week; one day ago is yesterday.
+  const daysAgo = (days) => new Date(Date.now() - days * 86_400_000).toISOString();
+  const timestamps = { yesterday: daysAgo(1), lastWeek: daysAgo(7), older: daysAgo(30) };
+
+  for (const [key, timestamp] of Object.entries(timestamps)) {
+    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"],
+      date: timestamp.slice(0, 10),
+      projectRoot,
+      scope: "project",
+      sync: false,
+      timestamp,
+      title: "Deploy key rotation",
+    });
+  }
+
+  const ids = async (phrase) =>
+    (await memory.searchMemory({ projectRoot, query: `deploy key rotation ${phrase}`, scope: "project" })).results.map(
+      (result) => result.id,
+    );
+
+  assert.deepEqual(await ids("yesterday"), [timestamps.yesterday]);
+  // On a Monday, yesterday is also in last week.
+  const lastWeek = await ids("last week");
+  assert.ok(lastWeek.includes(timestamps.lastWeek));
+  assert.ok(!lastWeek.includes(timestamps.older));
+  assert.deepEqual(await ids("today"), []);
+});
+
+test("search returns a snippet for a long event matched only by its date", async (t) => {
+  const originalRoot = process.env.HIPPOCAMP_GLOBAL_ROOT;
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "hippocamp-date-only-"));
+  const projectRoot = path.join(tempRoot, "date-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 });
+  });
+
+  await memory.appendEvent({
+    content: Array(30).fill("The weekly sync covered routine updates.").join("\n\n"),
+    cues: ["sync"],
+    date: "2026-08-05",
+    projectRoot,
+    scope: "project",
+    sync: false,
+    timestamp: "2026-08-05T10:00:00.000Z",
+    title: "Weekly sync",
+  });
+
+  const search = await memory.searchMemory({ projectRoot, query: "2026-08-05", scope: "project" });
+
+  assert.equal(search.results.length, 1);
+  assert.match(search.results[0].snippet, /^The weekly sync covered routine updates\./);
+  assert.ok(search.results[0].snippet.length <= 1200);
+});