memorix 0.7.11 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.0] — 2026-02-24
+
+### Added
+- **Session Lifecycle Management** — 3 new MCP tools for cross-session context continuity:
+  - `memorix_session_start` — Start a coding session, auto-inject context from previous sessions (summaries + key observations). Previous active sessions are auto-closed.
+  - `memorix_session_end` — End a session with structured summary (Goal/Discoveries/Accomplished/Files format). Summary is injected into the next session.
+  - `memorix_session_context` — Manually retrieve session history and context (useful after compaction recovery).
+- **Topic Key Upsert** — `memorix_store` now accepts an optional `topicKey` parameter. When an observation with the same `topicKey + projectId` already exists, it is **updated in-place** instead of creating a duplicate. `revisionCount` increments on each upsert. Prevents data bloat for evolving decisions, architecture docs, etc.
+- **`memorix_suggest_topic_key` tool** — Suggests stable topic keys from type + title using family heuristics (`architecture/*`, `bug/*`, `decision/*`, `config/*`, `discovery/*`, `pattern/*`). Supports CJK characters.
+- **Session persistence** — `sessions.json` with atomic writes and file locking for cross-process safety.
+- **Observation fields** — `topicKey`, `revisionCount`, `updatedAt`, `sessionId` added to `Observation` interface.
+- **30 new tests** — 16 session lifecycle tests + 14 topic key upsert tests (468 total).
+
+### Improved
+- **`storeObservation` API** — Now returns `{ observation, upserted }` instead of just `Observation`, enabling callers to distinguish new vs updated observations.
+
+### Inspired by
+- [Engram](https://github.com/alanbuscaglia/engram) — Session lifecycle design, topic_key upsert pattern, structured session summaries.
+
 ## [0.7.11] — 2026-02-24
 
 ### Added

package/dist/cli/index.js

@@ -111,10 +111,12 @@ __export(persistence_exports, {
   loadGraphJsonl: () => loadGraphJsonl,
   loadIdCounter: () => loadIdCounter,
   loadObservationsJson: () => loadObservationsJson,
+  loadSessionsJson: () => loadSessionsJson,
   migrateGlobalData: () => migrateGlobalData,
   saveGraphJsonl: () => saveGraphJsonl,
   saveIdCounter: () => saveIdCounter,
-  saveObservationsJson: () => saveObservationsJson
+  saveObservationsJson: () => saveObservationsJson,
+  saveSessionsJson: () => saveSessionsJson
 });
 import { promises as fs2 } from "fs";
 import path3 from "path";
@@ -333,6 +335,22 @@ async function loadIdCounter(projectDir2) {
     return 1;
   }
 }
+async function saveSessionsJson(projectDir2, sessions) {
+  const filePath = path3.join(projectDir2, "sessions.json");
+  await atomicWriteFile(filePath, JSON.stringify(sessions, null, 2));
+}
+async function loadSessionsJson(projectDir2) {
+  const filePath = path3.join(projectDir2, "sessions.json");
+  try {
+    const data = await fs2.readFile(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
 var DEFAULT_DATA_DIR;
 var init_persistence = __esm({
   "src/store/persistence.ts"() {
@@ -495,7 +513,7 @@ var init_graph = __esm({
 });
 
 // src/types.ts
-var OBSERVATION_ICONS;
+var OBSERVATION_ICONS, TOPIC_KEY_FAMILIES;
 var init_types = __esm({
   "src/types.ts"() {
     "use strict";
@@ -511,6 +529,14 @@ var init_types = __esm({
       "decision": "\u{1F7E4}",
       "trade-off": "\u2696\uFE0F"
     };
+    TOPIC_KEY_FAMILIES = {
+      "architecture": ["architecture", "design", "adr", "structure", "pattern"],
+      "bug": ["bugfix", "fix", "error", "regression", "crash", "problem-solution"],
+      "decision": ["decision", "trade-off", "choice", "strategy"],
+      "config": ["config", "setup", "env", "environment", "deployment"],
+      "discovery": ["discovery", "learning", "insight", "gotcha"],
+      "pattern": ["pattern", "convention", "standard", "best-practice"]
+    };
   }
 });
 
@@ -1090,7 +1116,8 @@ __export(observations_exports, {
   getProjectObservations: () => getProjectObservations,
   initObservations: () => initObservations,
   reindexObservations: () => reindexObservations,
-  storeObservation: () => storeObservation
+  storeObservation: () => storeObservation,
+  suggestTopicKey: () => suggestTopicKey
 });
 async function initObservations(dir) {
   projectDir = dir;
@@ -1099,8 +1126,16 @@ async function initObservations(dir) {
   nextId = await loadIdCounter(dir);
 }
 async function storeObservation(input) {
-  const id = nextId++;
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (input.topicKey) {
+    const existing = observations.find(
+      (o) => o.topicKey === input.topicKey && o.projectId === input.projectId
+    );
+    if (existing) {
+      return { observation: await upsertObservation(existing, input, now), upserted: true };
+    }
+  }
+  const id = nextId++;
   const contentForExtraction = [input.title, input.narrative, ...input.facts ?? []].join(" ");
   const extracted = extractEntities(contentForExtraction);
   const enrichedConcepts = enrichConcepts(input.concepts ?? [], extracted);
@@ -1131,7 +1166,10 @@ async function storeObservation(input) {
     tokens,
     createdAt: now,
     projectId: input.projectId,
-    hasCausalLanguage: extracted.hasCausalLanguage
+    hasCausalLanguage: extracted.hasCausalLanguage,
+    topicKey: input.topicKey,
+    revisionCount: 1,
+    sessionId: input.sessionId
   };
   observations.push(observation);
   const searchableText = [input.title, input.narrative, ...input.facts ?? []].join(" ");
@@ -1169,7 +1207,70 @@ async function storeObservation(input) {
       await saveIdCounter(projectDir, nextId);
     });
   }
-  return observation;
+  return { observation, upserted: false };
+}
+async function upsertObservation(existing, input, now) {
+  const contentForExtraction = [input.title, input.narrative, ...input.facts ?? []].join(" ");
+  const extracted = extractEntities(contentForExtraction);
+  const enrichedConcepts = enrichConcepts(input.concepts ?? [], extracted);
+  const userFiles = new Set((input.filesModified ?? []).map((f) => f.toLowerCase()));
+  const enrichedFiles = [...input.filesModified ?? []];
+  for (const f of extracted.files) {
+    if (!userFiles.has(f.toLowerCase())) enrichedFiles.push(f);
+  }
+  const fullText = [input.title, input.narrative, ...input.facts ?? [], ...enrichedFiles, ...enrichedConcepts].join(" ");
+  const tokens = countTextTokens(fullText);
+  existing.entityName = input.entityName;
+  existing.type = input.type;
+  existing.title = input.title;
+  existing.narrative = input.narrative;
+  existing.facts = input.facts ?? [];
+  existing.filesModified = enrichedFiles;
+  existing.concepts = enrichedConcepts;
+  existing.tokens = tokens;
+  existing.updatedAt = now;
+  existing.hasCausalLanguage = extracted.hasCausalLanguage;
+  existing.revisionCount = (existing.revisionCount ?? 1) + 1;
+  if (input.sessionId) existing.sessionId = input.sessionId;
+  const searchableText = [input.title, input.narrative, ...input.facts ?? []].join(" ");
+  const embedding = await generateEmbedding(searchableText);
+  const doc = {
+    id: `obs-${existing.id}`,
+    observationId: existing.id,
+    entityName: existing.entityName,
+    type: existing.type,
+    title: existing.title,
+    narrative: existing.narrative,
+    facts: existing.facts.join("\n"),
+    filesModified: enrichedFiles.join("\n"),
+    concepts: enrichedConcepts.map((c) => c.replace(/-/g, " ")).join(", "),
+    tokens,
+    createdAt: existing.createdAt,
+    projectId: existing.projectId,
+    accessCount: 0,
+    lastAccessedAt: "",
+    ...embedding ? { embedding } : {}
+  };
+  try {
+    const { removeObservation: removeObservation2 } = await Promise.resolve().then(() => (init_orama_store(), orama_store_exports));
+    await removeObservation2(`obs-${existing.id}`);
+  } catch {
+  }
+  await insertObservation(doc);
+  if (projectDir) {
+    await withFileLock(projectDir, async () => {
+      const diskObs = await loadObservationsJson(projectDir);
+      const idx = diskObs.findIndex((o) => o.id === existing.id);
+      if (idx >= 0) {
+        diskObs[idx] = existing;
+      } else {
+        diskObs.push(existing);
+      }
+      observations = diskObs;
+      await saveObservationsJson(projectDir, observations);
+    });
+  }
+  return existing;
 }
 function getObservation(id) {
   return observations.find((o) => o.id === id);
@@ -1180,6 +1281,19 @@ function getProjectObservations(projectId) {
 function getObservationCount2() {
   return observations.length;
 }
+function suggestTopicKey(type, title) {
+  let family = "general";
+  const typeLower = type.toLowerCase();
+  for (const [fam, keywords] of Object.entries(TOPIC_KEY_FAMILIES)) {
+    if (keywords.some((k) => typeLower.includes(k))) {
+      family = fam;
+      break;
+    }
+  }
+  const slug = title.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff\s-]/g, "").trim().replace(/\s+/g, "-").slice(0, 60);
+  if (!slug) return "";
+  return `${family}/${slug}`;
+}
 async function reindexObservations() {
   let count2 = 0;
   for (const obs of observations) {
@@ -1222,6 +1336,7 @@ var init_observations = __esm({
   "src/memory/observations.ts"() {
     "use strict";
     init_esm_shims();
+    init_types();
     init_orama_store();
     init_persistence();
     init_file_lock();
@@ -4377,6 +4492,138 @@ var init_engine3 = __esm({
   }
 });
 
+// src/memory/session.ts
+var session_exports = {};
+__export(session_exports, {
+  endSession: () => endSession,
+  getActiveSession: () => getActiveSession,
+  getSessionContext: () => getSessionContext,
+  listSessions: () => listSessions,
+  startSession: () => startSession
+});
+function generateSessionId() {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `sess-${ts}-${rand}`;
+}
+async function startSession(projectDir2, projectId, opts) {
+  const sessionId = opts?.sessionId || generateSessionId();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const session = {
+    id: sessionId,
+    projectId,
+    startedAt: now,
+    status: "active",
+    agent: opts?.agent
+  };
+  const previousContext = await getSessionContext(projectDir2, projectId);
+  await withFileLock(projectDir2, async () => {
+    const sessions = await loadSessionsJson(projectDir2);
+    for (const s of sessions) {
+      if (s.projectId === projectId && s.status === "active") {
+        s.status = "completed";
+        s.endedAt = now;
+        if (!s.summary) {
+          s.summary = "(session ended implicitly by new session start)";
+        }
+      }
+    }
+    sessions.push(session);
+    await saveSessionsJson(projectDir2, sessions);
+  });
+  return { session, previousContext };
+}
+async function endSession(projectDir2, sessionId, summary) {
+  let endedSession = null;
+  await withFileLock(projectDir2, async () => {
+    const sessions = await loadSessionsJson(projectDir2);
+    const session = sessions.find((s) => s.id === sessionId);
+    if (!session) return;
+    session.status = "completed";
+    session.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (summary) {
+      session.summary = summary;
+    }
+    endedSession = session;
+    await saveSessionsJson(projectDir2, sessions);
+  });
+  return endedSession;
+}
+async function getSessionContext(projectDir2, projectId, limit = 3) {
+  const sessions = await loadSessionsJson(projectDir2);
+  const allObs = await loadObservationsJson(projectDir2);
+  const projectSessions = sessions.filter((s) => s.projectId === projectId && s.status === "completed").sort((a, b) => new Date(b.endedAt || b.startedAt).getTime() - new Date(a.endedAt || a.startedAt).getTime()).slice(0, limit);
+  if (projectSessions.length === 0 && allObs.length === 0) {
+    return "";
+  }
+  const lines = [];
+  if (projectSessions.length > 0) {
+    const last = projectSessions[0];
+    lines.push(`## Previous Session`);
+    if (last.agent) {
+      lines.push(`Agent: ${last.agent}`);
+    }
+    lines.push(`Ended: ${last.endedAt || last.startedAt}`);
+    if (last.summary && last.summary !== "(session ended implicitly by new session start)") {
+      lines.push("");
+      lines.push(last.summary);
+    }
+    lines.push("");
+  }
+  const PRIORITY_TYPES = /* @__PURE__ */ new Set(["gotcha", "decision", "problem-solution", "trade-off", "discovery"]);
+  const TYPE_EMOJI = {
+    "gotcha": "\u{1F534}",
+    "decision": "\u{1F7E4}",
+    "problem-solution": "\u{1F7E1}",
+    "trade-off": "\u2696\uFE0F",
+    "discovery": "\u{1F7E3}",
+    "how-it-works": "\u{1F535}",
+    "what-changed": "\u{1F7E2}",
+    "why-it-exists": "\u{1F7E0}",
+    "session-request": "\u{1F3AF}"
+  };
+  const priorityObs = allObs.filter((o) => o.projectId === projectId && PRIORITY_TYPES.has(o.type)).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()).slice(0, 5);
+  if (priorityObs.length > 0) {
+    lines.push(`## Key Memories`);
+    for (const obs of priorityObs) {
+      const emoji = TYPE_EMOJI[obs.type] ?? "\u{1F4CC}";
+      const fact = obs.facts?.[0] ? ` \u2014 ${obs.facts[0]}` : "";
+      lines.push(`${emoji} ${obs.title}${fact}`);
+    }
+    lines.push("");
+  }
+  if (projectSessions.length > 1) {
+    lines.push(`## Session History (last ${projectSessions.length})`);
+    for (const s of projectSessions) {
+      const date = (s.endedAt || s.startedAt).slice(0, 10);
+      const agent = s.agent ? ` [${s.agent}]` : "";
+      const summary = s.summary ? ` \u2014 ${s.summary.split("\n")[0].replace(/^#+\s*/, "").slice(0, 80)}` : "";
+      lines.push(`- ${date}${agent}${summary}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+async function listSessions(projectDir2, projectId) {
+  const sessions = await loadSessionsJson(projectDir2);
+  if (projectId) {
+    return sessions.filter((s) => s.projectId === projectId);
+  }
+  return sessions;
+}
+async function getActiveSession(projectDir2, projectId) {
+  const sessions = await loadSessionsJson(projectDir2);
+  return sessions.find((s) => s.projectId === projectId && s.status === "active") || null;
+}
+var init_session = __esm({
+  "src/memory/session.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_persistence();
+    init_file_lock();
+  }
+});
+
 // src/dashboard/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -4838,14 +5085,17 @@ async function createMemorixServer(cwd, existingServer) {
         narrative: z.string().describe("Full description of the observation"),
         facts: z.array(z.string()).optional().describe('Structured facts (e.g., "Default timeout: 60s")'),
         filesModified: z.array(z.string()).optional().describe("Files involved"),
-        concepts: z.array(z.string()).optional().describe("Related concepts/keywords")
+        concepts: z.array(z.string()).optional().describe("Related concepts/keywords"),
+        topicKey: z.string().optional().describe(
+          'Optional topic identifier for upserts (e.g., "architecture/auth-model"). If an observation with the same topicKey already exists in this project, it will be UPDATED instead of creating a new one. Use memorix_suggest_topic_key to generate a stable key. Good for evolving decisions, architecture docs, etc.'
+        )
       }
     },
-    async ({ entityName, type, title, narrative, facts, filesModified, concepts }) => {
+    async ({ entityName, type, title, narrative, facts, filesModified, concepts, topicKey }) => {
       await graphManager.createEntities([
         { name: entityName, entityType: "auto", observations: [] }
       ]);
-      const obs = await storeObservation({
+      const { observation: obs, upserted } = await storeObservation({
         entityName,
         type,
         title,
@@ -4853,7 +5103,8 @@ async function createMemorixServer(cwd, existingServer) {
         facts,
         filesModified,
         concepts,
-        projectId: project.id
+        projectId: project.id,
+        topicKey
       });
       await graphManager.addObservations([
         { entityName, contents: [`[#${obs.id}] ${title}`] }
@@ -4867,19 +5118,47 @@ async function createMemorixServer(cwd, existingServer) {
       if (autoConcepts.length > 0) enrichmentParts.push(`+${autoConcepts.length} concepts enriched`);
       if (autoRelCount > 0) enrichmentParts.push(`+${autoRelCount} relations auto-created`);
       if (obs.hasCausalLanguage) enrichmentParts.push("causal language detected");
+      if (upserted) enrichmentParts.push(`topic upserted (rev ${obs.revisionCount ?? 1})`);
       const enrichment = enrichmentParts.length > 0 ? `
 Auto-enriched: ${enrichmentParts.join(", ")}` : "";
+      const action = upserted ? "\u{1F504} Updated" : "\u2705 Stored";
       return {
         content: [
           {
             type: "text",
-            text: `\u2705 Stored observation #${obs.id} "${title}" (~${obs.tokens} tokens)
-Entity: ${entityName} | Type: ${type} | Project: ${project.id}${enrichment}`
+            text: `${action} observation #${obs.id} "${title}" (~${obs.tokens} tokens)
+Entity: ${entityName} | Type: ${type} | Project: ${project.id}${obs.topicKey ? ` | Topic: ${obs.topicKey}` : ""}${enrichment}`
           }
         ]
       };
     }
   );
+  server.registerTool(
+    "memorix_suggest_topic_key",
+    {
+      title: "Suggest Topic Key",
+      description: 'Suggest a stable topic_key for memory upserts. Use this before memorix_store when you want evolving topics (like architecture decisions, config docs) to update a single observation over time instead of creating duplicates. Returns a key like "architecture/auth-model" or "bug/timeout-in-api-gateway".',
+      inputSchema: {
+        type: z.string().describe("Observation type (e.g., decision, architecture, bugfix, discovery)"),
+        title: z.string().describe("Observation title \u2014 used to generate the stable key")
+      }
+    },
+    async ({ type: obsType, title }) => {
+      const { suggestTopicKey: suggestTopicKey2 } = await Promise.resolve().then(() => (init_observations(), observations_exports));
+      const key = suggestTopicKey2(obsType, title);
+      if (!key) {
+        return {
+          content: [{ type: "text", text: "Could not suggest topic_key from the given input. Provide a more descriptive title." }],
+          isError: true
+        };
+      }
+      return {
+        content: [{ type: "text", text: `Suggested topic_key: \`${key}\`
+
+Use this as the \`topicKey\` parameter in \`memorix_store\` to enable upsert behavior.` }]
+      };
+    }
+  );
   server.registerTool(
     "memorix_search",
     {
@@ -5472,6 +5751,96 @@ ${skill.content}` }]
       };
     }
   );
+  server.registerTool(
+    "memorix_session_start",
+    {
+      title: "Start Session",
+      description: "Start a new coding session. Returns context from previous sessions so you can resume work seamlessly. Call this at the beginning of a session to track activity and get injected context. Any previous active session for this project will be auto-closed.",
+      inputSchema: {
+        sessionId: z.string().optional().describe("Custom session ID (auto-generated if omitted)"),
+        agent: z.string().optional().describe('Agent/IDE name (e.g., "cursor", "windsurf", "claude-code")')
+      }
+    },
+    async ({ sessionId, agent }) => {
+      const { startSession: startSession2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+      const result = await startSession2(projectDir2, project.id, { sessionId, agent });
+      const lines = [
+        `\u2705 Session started: ${result.session.id}`,
+        `Project: ${project.name} (${project.id})`,
+        result.session.agent ? `Agent: ${result.session.agent}` : "",
+        ""
+      ];
+      if (result.previousContext) {
+        lines.push("---", "\u{1F4CB} **Context from previous sessions:**", "", result.previousContext);
+      } else {
+        lines.push("No previous session context found. This appears to be a fresh project.");
+      }
+      return {
+        content: [{ type: "text", text: lines.filter(Boolean).join("\n") }]
+      };
+    }
+  );
+  server.registerTool(
+    "memorix_session_end",
+    {
+      title: "End Session",
+      description: "End a coding session with a structured summary. This summary will be injected into the next session so the next agent can resume work seamlessly.\n\nRecommended summary format:\n## Goal\n[What we were working on]\n\n## Discoveries\n- [Technical findings, gotchas, learnings]\n\n## Accomplished\n- \u2705 [Completed tasks]\n- \u{1F532} [Pending for next session]\n\n## Relevant Files\n- path/to/file \u2014 [what changed]",
+      inputSchema: {
+        sessionId: z.string().describe("Session ID to close (from memorix_session_start)"),
+        summary: z.string().optional().describe("Structured session summary (Goal/Discoveries/Accomplished/Files format)")
+      }
+    },
+    async ({ sessionId, summary }) => {
+      const { endSession: endSession2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+      const session = await endSession2(projectDir2, sessionId, summary);
+      if (!session) {
+        return {
+          content: [{ type: "text", text: `Session "${sessionId}" not found.` }],
+          isError: true
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: `\u2705 Session "${sessionId}" completed.
+Duration: ${session.startedAt} \u2192 ${session.endedAt}
+${summary ? "Summary saved for next session context injection." : "No summary provided \u2014 consider adding one for better cross-session context."}`
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "memorix_session_context",
+    {
+      title: "Session Context",
+      description: "Get context from previous coding sessions. Use this after compaction to recover lost context, or to manually review session history. Returns previous session summaries and key observations.",
+      inputSchema: {
+        limit: z.number().optional().describe("Number of recent sessions to include (default: 3)")
+      }
+    },
+    async ({ limit }) => {
+      const { getSessionContext: getSessionContext2, listSessions: listSessions2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+      const context = await getSessionContext2(projectDir2, project.id, limit ?? 3);
+      const sessions = await listSessions2(projectDir2, project.id);
+      const activeSessions = sessions.filter((s) => s.status === "active");
+      const completedSessions = sessions.filter((s) => s.status === "completed");
+      const header = [
+        `## Session Stats`,
+        `- Active: ${activeSessions.length}`,
+        `- Completed: ${completedSessions.length}`,
+        `- Total: ${sessions.length}`,
+        ""
+      ];
+      if (!context) {
+        return {
+          content: [{ type: "text", text: header.join("\n") + "\nNo previous session context available." }]
+        };
+      }
+      return {
+        content: [{ type: "text", text: header.join("\n") + context }]
+      };
+    }
+  );
   let dashboardRunning = false;
   server.registerTool(
     "memorix_dashboard",