hippocamp 0.1.1 → 0.2.0

package/scripts/hippocamp-memory.cjs

@@ -1,9 +1,11 @@
+const crypto = require("node:crypto");
 const fsSync = require("node:fs");
 const fs = require("node:fs/promises");
 const { execFile } = require("node:child_process");
 const path = require("node:path");
 const os = require("node:os");
 const { promisify } = require("node:util");
+const MiniSearch = require("minisearch");
 
 const execFileAsync = promisify(execFile);
 
@@ -21,7 +23,29 @@ const DEFAULT_PROJECT_FILES = [
 ];
 
 const EVENT_INDEX_VERSION = 1;
-const EVENT_SEARCH_THRESHOLD = 20;
+const SEARCH_CANDIDATE_LIMIT = 60;
+const SEARCH_FIELD_BOOST = { cues: 3, heading: 2 };
+const SEARCH_FUZZY_DISTANCE = 0.2;
+const SEARCH_INDEX_CACHE_LIMIT = 8;
+const SEARCH_EXCERPT_MAX_CHARS = 1200;
+const searchIndexCache = new Map();
+const PROCESS_SESSION_ID = `mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+
+const AGENT_NAME_ALIASES = {
+  claude: "claude",
+  "claude-code": "claude",
+  "claude code": "claude",
+  anthropic: "claude",
+  codex: "codex",
+  "openai-codex": "codex",
+  cursor: "cursor",
+  "cursor-ide": "cursor",
+  windsurf: "windsurf",
+  grok: "grok",
+  "grok-build": "grok",
+  vscode: "vscode",
+  "visual-studio-code": "vscode",
+};
 
 function expandHomePath(value) {
   if (!value) {
@@ -99,6 +123,15 @@ function findRepositoryRootSync(startPath) {
   return path.basename(commonDir) === ".git" ? path.dirname(commonDir) : gitRoot;
 }
 
+function isProjectRepository(projectRoot) {
+  const resolvedProjectRoot = getProjectRoot(projectRoot);
+  return (
+    fsSync.existsSync(resolvedProjectRoot) &&
+    fsSync.statSync(resolvedProjectRoot).isDirectory() &&
+    findGitRootSync(resolvedProjectRoot) !== null
+  );
+}
+
 function slugifyProjectName(value) {
   const slug = value
     .toLowerCase()
@@ -249,6 +282,124 @@ function formatCuesSection(cues) {
   return ["Cues:", ...normalizedCues.map((cue) => `- ${cue}`)].join("\n");
 }
 
+function normalizeAgentName(value) {
+  const raw = String(value || "").trim().toLowerCase();
+
+  if (!raw) {
+    return null;
+  }
+
+  const withoutVersion = raw.replace(/\/.*$/, "").replace(/\s+v?\d+(\.\d+)*$/i, "").trim();
+  const compact = withoutVersion.replace(/_/g, "-");
+
+  if (AGENT_NAME_ALIASES[compact]) {
+    return AGENT_NAME_ALIASES[compact];
+  }
+
+  if (AGENT_NAME_ALIASES[withoutVersion]) {
+    return AGENT_NAME_ALIASES[withoutVersion];
+  }
+
+  const firstToken = compact.split(/[\s/]+/).filter(Boolean)[0];
+
+  if (firstToken && AGENT_NAME_ALIASES[firstToken]) {
+    return AGENT_NAME_ALIASES[firstToken];
+  }
+
+  const slug = normalizeCue(compact);
+
+  return slug || null;
+}
+
+function detectAgentFromEnvironment() {
+  if (process.env.CLAUDE_CODE || process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT) {
+    return "claude";
+  }
+
+  if (process.env.CODEX_HOME || process.env.CODEX_CI || process.env.OPENAI_CODEX) {
+    return "codex";
+  }
+
+  if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_AGENT || process.env.CURSOR_SESSION_ID) {
+    return "cursor";
+  }
+
+  if (process.env.GROK_HOME || process.env.GROK_BUILD || process.env.XAI_GROK) {
+    return "grok";
+  }
+
+  return null;
+}
+
+function resolveWriteAttribution({ agent, session, clientName } = {}) {
+  const resolvedAgent =
+    normalizeAgentName(agent) ||
+    normalizeAgentName(process.env.HIPPOCAMP_AGENT) ||
+    normalizeAgentName(clientName) ||
+    detectAgentFromEnvironment();
+
+  const envSession = String(process.env.HIPPOCAMP_SESSION || "").trim();
+  const resolvedSession = String(session || "").trim() || envSession || PROCESS_SESSION_ID;
+
+  return {
+    agent: resolvedAgent || null,
+    session: resolvedSession || null,
+  };
+}
+
+function formatAttributionSection({ agent, session } = {}) {
+  const lines = [];
+
+  if (agent) {
+    lines.push(`Agent: ${agent}`);
+  }
+
+  if (session) {
+    lines.push(`Session: ${session}`);
+  }
+
+  return lines.join("\n");
+}
+
+function extractAttributionFromEventLines(lines) {
+  let agent = null;
+  let session = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      if (agent || session) {
+        break;
+      }
+
+      continue;
+    }
+
+    const agentMatch = trimmed.match(/^Agent:\s*(.+)$/i);
+
+    if (agentMatch) {
+      agent = normalizeAgentName(agentMatch[1]) || agentMatch[1].trim();
+      continue;
+    }
+
+    const sessionMatch = trimmed.match(/^Session:\s*(.+)$/i);
+
+    if (sessionMatch) {
+      session = sessionMatch[1].trim();
+      continue;
+    }
+
+    // Provenance lines sit at the top of the body; stop at cues or free text.
+    break;
+  }
+
+  return {
+    agent: agent || null,
+    session: session || null,
+  };
+}
+
 async function ensureParentDirectory(filePath) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
 }
@@ -536,10 +687,13 @@ function parseEventBlocks(content) {
     const blockLines = lines.slice(startIndex, endIndex);
     const heading = parseEventHeading(blockLines[0]);
     const bodyLines = blockLines.slice(1);
+    const attribution = extractAttributionFromEventLines(bodyLines);
 
     return {
       id: heading.id,
       heading: heading.heading,
+      agent: attribution.agent,
+      session: attribution.session,
       cues: extractCuesFromEventLines(bodyLines),
       content: blockLines.join("\n").trim(),
       body: bodyLines.join("\n").trim(),
@@ -552,11 +706,23 @@ function buildEventIndex(markdownContent, markdownPath) {
   return {
     version: EVENT_INDEX_VERSION,
     path: path.posix.basename(markdownPath),
-    events: parseEventBlocks(markdownContent).map((event) => ({
-      id: event.id,
-      heading: event.heading,
-      cues: event.cues,
-    })),
+    events: parseEventBlocks(markdownContent).map((event) => {
+      const entry = {
+        id: event.id,
+        heading: event.heading,
+        cues: event.cues,
+      };
+
+      if (event.agent) {
+        entry.agent = event.agent;
+      }
+
+      if (event.session) {
+        entry.session = event.session;
+      }
+
+      return entry;
+    }),
   };
 }
 
@@ -695,31 +861,71 @@ function scoreSearchValues(queryInfo, values) {
   return Math.max(phraseScore, exactScore, fuzzyScore);
 }
 
-function createFallbackSnippet(content) {
-  const compact = content.replace(/\s+/g, " ").trim();
-  return compact.length > 220 ? `${compact.slice(0, 217)}...` : compact;
+// Split a paragraph over the excerpt limit into whole-sentence chunks so a
+// long matching paragraph is still searchable without cropping mid-sentence.
+function splitOversizedBlock(block) {
+  if (block.length <= SEARCH_EXCERPT_MAX_CHARS) {
+    return [block];
+  }
+
+  const chunks = [];
+  let current = "";
+
+  for (const sentence of block.split(/(?<=[.!?])\s+|\n+/)) {
+    const next = current ? `${current} ${sentence}` : sentence;
+
+    if (next.length <= SEARCH_EXCERPT_MAX_CHARS) {
+      current = next;
+      continue;
+    }
+
+    if (current) {
+      chunks.push(current);
+    }
+
+    current = sentence.length <= SEARCH_EXCERPT_MAX_CHARS ? sentence : "";
+  }
+
+  if (current) {
+    chunks.push(current);
+  }
+
+  return chunks;
 }
 
-function createSearchSnippet(content, query) {
-  const haystack = content.toLowerCase();
-  const needle = query.toLowerCase();
-  const index = haystack.indexOf(needle);
+function createSearchExcerpt(content, queryInfo) {
+  const trimmed = content.trim();
 
-  if (index < 0) {
+  if (!trimmed) {
     return null;
   }
 
-  const radius = 80;
-  const start = Math.max(0, index - radius);
-  const end = Math.min(content.length, index + query.length + radius);
-  const prefix = start > 0 ? "..." : "";
-  const suffix = end < content.length ? "..." : "";
-  const snippet = content
-    .slice(start, end)
-    .replace(/\s+/g, " ")
-    .trim();
+  if (trimmed.length <= SEARCH_EXCERPT_MAX_CHARS) {
+    return trimmed;
+  }
+
+  const blocks = trimmed
+    .split(/\n\s*\n+/)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .filter((block) => !/^(?:Agent:|Session:|Cues:)\s*/i.test(block))
+    .flatMap(splitOversizedBlock);
+
+  if (!blocks.length) {
+    return null;
+  }
+
+  const index = new MiniSearch({
+    fields: ["text"],
+    idField: "position",
+    tokenize: tokenizeSearchText,
+    processTerm: (term) => term,
+  });
+
+  index.addAll(blocks.map((text, position) => ({ position, text })));
 
-  return `${prefix}${snippet}${suffix}`;
+  const [best] = index.search(queryInfo.normalized, { fuzzy: SEARCH_FUZZY_DISTANCE });
+  return best ? blocks[best.id] : null;
 }
 
 async function readMemoryFile({ scope, path: relativePath, projectRoot }) {
@@ -737,6 +943,11 @@ async function readMemoryFile({ scope, path: relativePath, projectRoot }) {
 
 async function writeMemoryFile({ scope, path: relativePath, content, projectRoot, sync = true }) {
   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.");
+  }
+
   const nextContent = ensureTrailingNewline(requireNonEmptyString(content, "content"));
 
   await ensureParentDirectory(target.absolutePath);
@@ -774,13 +985,19 @@ async function appendEvent({
   title,
   date = new Date().toISOString().slice(0, 10),
   timestamp = new Date().toISOString(),
+  agent,
+  session,
+  clientName,
 }) {
   const body = requireNonEmptyString(content, "content");
+  const attribution = resolveWriteAttribution({ agent, session, clientName });
   const normalizedCues = normalizeCueList(cues);
-  const eventBody =
+  const cuedBody =
     normalizedCues.length && !hasCuesSection(body)
       ? `${formatCuesSection(normalizedCues)}\n\n${body.trim()}`
       : body.trim();
+  const attributionSection = formatAttributionSection(attribution);
+  const eventBody = attributionSection ? `${attributionSection}\n\n${cuedBody}` : cuedBody;
   const heading = title ? `## ${timestamp} — ${title.trim()}` : `## ${timestamp}`;
   const eventBlock = `${heading}\n\n${eventBody}\n`;
   const relativePath = `events/${date}.md`;
@@ -807,13 +1024,17 @@ async function appendEvent({
         reason: "sync_disabled",
       };
 
+  const parsed = parseEventBlocks(eventBlock)[0];
+
   return {
     scope,
     root: target.root,
     path: target.path,
     timestamp,
     title: title?.trim() || null,
-    cues: parseEventBlocks(eventBlock)[0]?.cues || [],
+    agent: parsed?.agent || attribution.agent,
+    session: parsed?.session || attribution.session,
+    cues: parsed?.cues || [],
     indexPath,
     sync: syncResult,
   };
@@ -854,32 +1075,8 @@ async function listEventFiles(root) {
   };
 }
 
-function scoreEventEntry(queryInfo, event) {
-  const cueScore = scoreSearchValues(queryInfo, event.cues || []);
-  const headingScore = scoreSearchValues(queryInfo, [event.heading || "", event.id || ""]);
-  const score = cueScore * 100 + headingScore * 60;
-  const match = cueScore >= headingScore ? "cues" : "heading";
-
-  return {
-    score,
-    match,
-  };
-}
-
-async function getEventBlockById(markdownPath, eventId) {
-  const content = await readFileIfExists(markdownPath);
-
-  if (content === null) {
-    return null;
-  }
-
-  return parseEventBlocks(content).find((event) => event.id === eventId) || null;
-}
-
-async function searchEventIndexes({ scope, root, queryInfo }) {
-  const eventFiles = await listEventFiles(root);
-  const indexedMarkdownFiles = new Set();
-  const candidates = [];
+async function collectEventDocuments({ scope, eventFiles }) {
+  const documents = [];
 
   for (const indexName of eventFiles.indexes) {
     const indexPath = path.join(eventFiles.eventsDir, indexName);
@@ -897,151 +1094,212 @@ async function searchEventIndexes({ scope, root, queryInfo }) {
       continue;
     }
 
-    indexedMarkdownFiles.add(markdownName);
+    const content = await readFileIfExists(path.join(eventFiles.eventsDir, markdownName));
+    const blocks = new Map();
+
+    for (const block of parseEventBlocks(content || "")) {
+      if (!blocks.has(block.id)) {
+        blocks.set(block.id, block);
+      }
+    }
 
     for (const event of index.events) {
-      const eventScore = scoreEventEntry(queryInfo, event);
+      const block = blocks.get(event.id);
 
-      if (eventScore.score < EVENT_SEARCH_THRESHOLD) {
+      if (!block) {
         continue;
       }
 
-      candidates.push({
+      documents.push({
         scope,
         path: `events/${markdownName}`,
-        markdownPath: path.join(eventFiles.eventsDir, markdownName),
         id: event.id,
         heading: event.heading,
         cues: normalizeCueList(event.cues),
-        score: Math.round(eventScore.score),
-        match: eventScore.match,
+        body: block.body,
       });
     }
   }
 
-  for (const markdownName of eventFiles.markdownFiles) {
-    if (indexedMarkdownFiles.has(markdownName)) {
-      continue;
-    }
-
-    const markdownPath = path.join(eventFiles.eventsDir, markdownName);
-    const content = await readFileIfExists(markdownPath);
+  return {
+    scannedFiles: eventFiles.indexes.length,
+    documents,
+  };
+}
 
-    if (content === null) {
-      continue;
-    }
+async function listCuratedMarkdownFiles(scope, root) {
+  const markdownFiles = await walkMarkdownFiles(root);
 
-    for (const event of parseEventBlocks(content)) {
-      const eventScore = scoreEventEntry(queryInfo, event);
+  return markdownFiles.filter(
+    (relativePath) =>
+      !relativePath.startsWith("events/") && (scope !== "global" || !relativePath.startsWith("projects/")),
+  );
+}
 
-      if (eventScore.score < EVENT_SEARCH_THRESHOLD) {
-        continue;
-      }
+async function collectMarkdownDocuments({ scope, root, curatedFiles }) {
+  const documents = [];
 
-      candidates.push({
-        scope,
-        path: `events/${markdownName}`,
-        markdownPath,
-        id: event.id,
-        heading: event.heading,
-        cues: event.cues,
-        score: Math.round(eventScore.score),
-        match: eventScore.match,
-      });
-    }
+  for (const relativePath of curatedFiles) {
+    documents.push({
+      scope,
+      path: relativePath,
+      body: await fs.readFile(path.join(root, relativePath), "utf8"),
+    });
   }
 
-  const results = [];
-  const sortedCandidates = candidates.sort((left, right) => right.score - left.score).slice(0, 60);
+  return {
+    scannedFiles: documents.length,
+    documents,
+  };
+}
+
+function buildSearchIndex(documents) {
+  const index = new MiniSearch({
+    fields: ["cues", "heading", "body"],
+    idField: "position",
+    tokenize: tokenizeSearchText,
+    processTerm: (term) => term,
+  });
 
-  for (const candidate of sortedCandidates) {
-    const block = await getEventBlockById(candidate.markdownPath, candidate.id);
+  index.addAll(
+    documents.map((document, position) => ({
+      position,
+      cues: (document.cues || []).join(" "),
+      heading: document.heading || document.path,
+      body: document.body,
+    })),
+  );
 
-    if (!block) {
-      continue;
-    }
+  return index;
+}
 
-    results.push({
-      scope: candidate.scope,
-      path: candidate.path,
-      id: candidate.id,
-      heading: candidate.heading,
-      cues: candidate.cues,
-      score: candidate.score,
-      match: candidate.match,
-      snippet: createSearchSnippet(block.content, queryInfo.original) || createFallbackSnippet(block.body),
-    });
+function rankSearchDocuments(queryInfo, { index, documents }) {
+  return index
+    .search(queryInfo.normalized, {
+      boost: SEARCH_FIELD_BOOST,
+      fuzzy: SEARCH_FUZZY_DISTANCE,
+    })
+    .slice(0, SEARCH_CANDIDATE_LIMIT)
+    .map((hit) => ({
+      document: documents[hit.id],
+      score: Math.round(hit.score * 100) / 100,
+    }));
+}
+
+function toSearchResult(queryInfo, { document, score }) {
+  const snippet = createSearchExcerpt(document.body, queryInfo);
+
+  if (!snippet) {
+    return null;
+  }
+
+  if (!document.id) {
+    return {
+      scope: document.scope,
+      path: document.path,
+      score,
+      match: scoreSearchValues(queryInfo, [document.path]) > 0 ? "path" : "body",
+      snippet,
+    };
   }
 
+  const cueScore = scoreSearchValues(queryInfo, document.cues);
+  const headingScore = scoreSearchValues(queryInfo, [document.heading || "", document.id]);
+
   return {
-    scannedFiles: eventFiles.indexes.length + eventFiles.markdownFiles.length - indexedMarkdownFiles.size,
-    results,
+    scope: document.scope,
+    path: document.path,
+    id: document.id,
+    heading: document.heading,
+    cues: document.cues,
+    score,
+    match: cueScore > 0 && cueScore >= headingScore ? "cues" : headingScore > 0 ? "heading" : "body",
+    snippet,
   };
 }
 
-async function searchMarkdownFiles({ scope, root, queryInfo }) {
-  const markdownFiles = await walkMarkdownFiles(root);
-  const scopedFiles =
-    scope === "global"
-      ? markdownFiles.filter((relativePath) => !relativePath.startsWith("projects/"))
-      : markdownFiles;
-  const results = [];
-  let scannedFiles = 0;
-
-  for (const relativePath of scopedFiles) {
-    if (relativePath.startsWith("events/")) {
-      continue;
+async function loadSearchIndex(scopes, projectRoot) {
+  const sources = [];
+  const signature = [];
+
+  for (const scope of scopes) {
+    const root = getScopeRoot(scope, projectRoot);
+    const eventFiles = await listEventFiles(root);
+    const curatedFiles = await listCuratedMarkdownFiles(scope, root);
+    const filePaths = [
+      ...[...eventFiles.indexes, ...eventFiles.markdownFiles].map((name) => path.join(eventFiles.eventsDir, name)),
+      ...curatedFiles.map((relativePath) => path.join(root, relativePath)),
+    ];
+
+    for (const filePath of filePaths) {
+      const stats = await statIfExists(filePath);
+      signature.push(`${filePath}:${stats?.mtimeMs}:${stats?.size}`);
     }
 
-    scannedFiles += 1;
+    sources.push({ scope, root, eventFiles, curatedFiles });
+  }
 
-    const absolutePath = path.join(root, relativePath);
-    const content = await fs.readFile(absolutePath, "utf8");
-    const pathScore = scoreSearchValues(queryInfo, [relativePath]);
-    const bodyScore = scoreSearchValues(queryInfo, [content]);
-    const score = pathScore * 70 + bodyScore * 40;
+  const cacheKey = sources.map((source) => `${source.scope}:${source.root}`).join("|");
+  const cached = searchIndexCache.get(cacheKey);
+  const signatureText = signature.join("\n");
 
-    if (score < EVENT_SEARCH_THRESHOLD) {
-      continue;
-    }
+  if (cached?.signature === signatureText) {
+    return cached;
+  }
 
-    results.push({
-      scope,
-      path: relativePath,
-      score: Math.round(score),
-      match: pathScore >= bodyScore ? "path" : "body",
-      snippet: createSearchSnippet(content, queryInfo.original) || createFallbackSnippet(content),
-    });
+  const documents = [];
+  let scannedFiles = 0;
+
+  for (const source of sources) {
+    const eventDocuments = await collectEventDocuments(source);
+    const markdownDocuments = await collectMarkdownDocuments(source);
+
+    scannedFiles += eventDocuments.scannedFiles + markdownDocuments.scannedFiles;
+    documents.push(...eventDocuments.documents, ...markdownDocuments.documents);
   }
 
-  return {
+  const loaded = {
+    signature: signatureText,
+    documents,
     scannedFiles,
-    results,
+    index: buildSearchIndex(documents),
   };
+
+  searchIndexCache.delete(cacheKey);
+  searchIndexCache.set(cacheKey, loaded);
+
+  if (searchIndexCache.size > SEARCH_INDEX_CACHE_LIMIT) {
+    searchIndexCache.delete(searchIndexCache.keys().next().value);
+  }
+
+  return loaded;
 }
 
-async function searchMemory({ query, scope = "both", projectRoot, maxResults = 10 }) {
+async function searchMemory({ query, scope = "both", projectRoot, maxResults = 5 }) {
   const queryInfo = createQueryInfo(query);
-  const clampedMaxResults = Math.max(1, Math.min(Number(maxResults) || 10, 20));
+  const clampedMaxResults = Math.max(1, Math.min(Number(maxResults) || 5, 20));
   const scopes = scope === "both" ? ["global", "project"] : [scope];
+  const search = await loadSearchIndex(scopes, projectRoot);
   const results = [];
-  let scannedFiles = 0;
 
-  for (const itemScope of scopes) {
-    const root = getScopeRoot(itemScope, projectRoot);
-    const eventSearch = await searchEventIndexes({ scope: itemScope, root, queryInfo });
-    const markdownSearch = await searchMarkdownFiles({ scope: itemScope, root, queryInfo });
+  if (queryInfo.tokens.length && search.documents.length) {
+    for (const candidate of rankSearchDocuments(queryInfo, search)) {
+      const result = toSearchResult(queryInfo, candidate);
 
-    scannedFiles += eventSearch.scannedFiles + markdownSearch.scannedFiles;
-    results.push(...eventSearch.results, ...markdownSearch.results);
-  }
+      if (result) {
+        results.push(result);
+      }
 
-  const rankedResults = results.sort((left, right) => right.score - left.score).slice(0, clampedMaxResults);
+      if (results.length >= clampedMaxResults) {
+        break;
+      }
+    }
+  }
 
   return {
     query: queryInfo.original,
-    scannedFiles,
-    results: rankedResults,
+    scannedFiles: search.scannedFiles,
+    results,
   };
 }
 
@@ -1128,6 +1386,7 @@ module.exports = {
   getGlobalRoot,
   getProjectRoot,
   getProjectSlug,
+  isProjectRepository,
   getScopeRoot,
   readMemoryFile,
   writeMemoryFile,
@@ -1137,4 +1396,6 @@ module.exports = {
   syncMemory,
   getDefaultSyncPaths,
   wakeUp,
+  resolveWriteAttribution,
+  PROCESS_SESSION_ID,
 };