@mneme-ai/core 0.22.2 → 0.23.0

package/dist/wisdom/session.js

@@ -0,0 +1,193 @@
+/**
+ * Conversational session memory — path-aware ask context across invocations.
+ *
+ * Why this exists: when a user runs `mneme ask` twice in a row, the second
+ * question almost always builds on the first. Without session memory, every
+ * ask is a cold start; with it, Q2 search is constrained by the commits and
+ * files surfaced in Q1, and topic vocabulary accumulates.
+ *
+ * Storage is a small JSON file at `<repoRoot>/.mneme/session.json`. We keep
+ * it deliberately separate from the SQLite store: sessions are short-lived
+ * (1-hour idle expiry), human-readable, and cheap to nuke. SQLite is the
+ * permanent record; this is the scratch pad.
+ *
+ * Concurrency: writes go through a temp-file rename so a crashed/half-written
+ * write never corrupts the file readers see.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Maximum turns retained in a single session. */
+export const MAX_TURNS = 20;
+/** Idle timeout in milliseconds (1 hour). */
+export const SESSION_IDLE_MS = 60 * 60 * 1000;
+/** Number of recent turns considered when building context. */
+const CONTEXT_TURN_WINDOW = 5;
+function sessionPath(repoRoot) {
+    return join(repoRoot, ".mneme", "session.json");
+}
+/** Read session from .mneme/session.json — returns null if expired/missing. */
+export function readSession(repoRoot, nowMs = Date.now()) {
+    const path = sessionPath(repoRoot);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const s = parsed;
+    if (typeof s.startedAt !== "string" || typeof s.lastActivityAt !== "string" || !Array.isArray(s.turns)) {
+        return null;
+    }
+    const lastMs = Date.parse(s.lastActivityAt);
+    if (Number.isNaN(lastMs) || nowMs - lastMs > SESSION_IDLE_MS) {
+        return null;
+    }
+    // Defensive normalization — discard any malformed turns rather than throw.
+    const turns = [];
+    for (const t of s.turns) {
+        if (!t || typeof t !== "object")
+            continue;
+        const turn = t;
+        if (typeof turn.at !== "string" ||
+            typeof turn.question !== "string" ||
+            !Array.isArray(turn.topHashes) ||
+            !Array.isArray(turn.topFiles) ||
+            typeof turn.confidence !== "string") {
+            continue;
+        }
+        turns.push({
+            at: turn.at,
+            question: turn.question,
+            topHashes: turn.topHashes.filter((x) => typeof x === "string"),
+            topFiles: turn.topFiles.filter((x) => typeof x === "string"),
+            confidence: turn.confidence,
+        });
+    }
+    return { startedAt: s.startedAt, lastActivityAt: s.lastActivityAt, turns };
+}
+function atomicWrite(path, contents) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            // If we cannot create the .mneme dir (e.g. read-only fs in tests), no-op.
+            return;
+        }
+    }
+    // Per-pid + timestamp temp suffix avoids two concurrent writers clobbering
+    // each other's tmp file before the rename.
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        writeFileSync(tmp, contents, "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        // Cleanup any orphan temp file; swallow — session is best-effort.
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Append a turn + write back. Auto-rotates when >MAX_TURNS turns. */
+export function appendTurn(repoRoot, turn) {
+    const nowIso = new Date().toISOString();
+    const existing = readSession(repoRoot, Date.now());
+    const session = existing
+        ? {
+            startedAt: existing.startedAt,
+            lastActivityAt: nowIso,
+            turns: [...existing.turns, turn],
+        }
+        : {
+            startedAt: nowIso,
+            lastActivityAt: nowIso,
+            turns: [turn],
+        };
+    if (session.turns.length > MAX_TURNS) {
+        session.turns = session.turns.slice(session.turns.length - MAX_TURNS);
+    }
+    atomicWrite(sessionPath(repoRoot), JSON.stringify(session, null, 2));
+}
+/** Reset session (e.g. user runs `mneme reset-session`). */
+export function clearSession(repoRoot) {
+    const path = sessionPath(repoRoot);
+    if (!existsSync(path))
+        return;
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        /* ignore — best-effort cleanup */
+    }
+}
+/**
+ * Cheap noun-phrase extraction. We are not building an NLP pipeline; we just
+ * want a stable bag of topic tokens that survives across turns. Anything
+ * fancier (POS tagging, real chunkers) would dwarf the rest of `mneme ask`.
+ */
+const STOP_WORDS = new Set([
+    "the", "a", "an", "and", "or", "but", "if", "of", "in", "on", "at", "to",
+    "for", "with", "by", "from", "as", "is", "are", "was", "were", "be", "been",
+    "being", "this", "that", "these", "those", "it", "its", "i", "you", "we",
+    "they", "he", "she", "do", "does", "did", "can", "could", "should", "would",
+    "will", "shall", "may", "might", "must", "have", "has", "had", "what", "why",
+    "how", "when", "where", "who", "which", "there", "here", "not", "no", "yes",
+    "so", "than", "then", "about", "into", "out", "up", "down", "over", "under",
+    "very", "just", "only", "also", "any", "some", "all", "each", "every", "my",
+    "your", "our", "their", "his", "her", "me", "us", "them", "him",
+]);
+function extractTopics(question) {
+    const out = [];
+    for (const raw of question.toLowerCase().split(/[^a-z0-9_]+/)) {
+        if (raw.length < 3)
+            continue;
+        if (STOP_WORDS.has(raw))
+            continue;
+        if (/^\d+$/.test(raw))
+            continue;
+        out.push(raw);
+    }
+    return out;
+}
+/**
+ * Build a "session context" for retrieval — accumulates hashes/files/topics
+ * from recent turns to bias search. Used by the next ask.
+ */
+export function buildSessionContext(session) {
+    const ctx = {
+        recentHashes: new Set(),
+        recentFiles: new Set(),
+        recentTopics: new Map(),
+    };
+    if (!session)
+        return ctx;
+    const turns = session.turns.slice(-CONTEXT_TURN_WINDOW);
+    for (const t of turns) {
+        for (const h of t.topHashes)
+            ctx.recentHashes.add(h);
+        for (const f of t.topFiles)
+            ctx.recentFiles.add(f);
+        for (const topic of extractTopics(t.question)) {
+            ctx.recentTopics.set(topic, (ctx.recentTopics.get(topic) ?? 0) + 1);
+        }
+    }
+    return ctx;
+}
+//# sourceMappingURL=session.js.map

package/dist/wisdom/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/wisdom/session.ts"],"names":[],"mappings":"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"}

package/dist/wisdom/session.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session.test.d.ts.map

package/dist/wisdom/session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.d.ts","sourceRoot":"","sources":["../../src/wisdom/session.test.ts"],"names":[],"mappings":""}

package/dist/wisdom/session.test.js

@@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { appendTurn, buildSessionContext, clearSession, readSession, SESSION_IDLE_MS, } from "./session.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mneme-session-test-"));
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+const sampleTurn = (i) => ({
+    at: new Date(2026, 4, 1, 12, i).toISOString(),
+    question: `Why does payment retry fail in handler ${i}?`,
+    topHashes: [`hash${i}a`, `hash${i}b`],
+    topFiles: [`src/payment/handler${i}.ts`],
+    confidence: "medium",
+});
+describe("session — round-trip", () => {
+    it("appends a turn and reads it back", () => {
+        appendTurn(tmpDir, sampleTurn(1));
+        const s = readSession(tmpDir);
+        expect(s).not.toBeNull();
+        expect(s.turns).toHaveLength(1);
+        expect(s.turns[0].question).toContain("payment");
+        expect(s.turns[0].topHashes).toEqual(["hash1a", "hash1b"]);
+    });
+    it("preserves turn order across multiple appends", () => {
+        appendTurn(tmpDir, sampleTurn(1));
+        appendTurn(tmpDir, sampleTurn(2));
+        appendTurn(tmpDir, sampleTurn(3));
+        const s = readSession(tmpDir);
+        expect(s.turns.map((t) => t.topHashes[0])).toEqual(["hash1a", "hash2a", "hash3a"]);
+    });
+});
+describe("session — expiration", () => {
+    it("returns null when last activity is older than 1 hour", () => {
+        appendTurn(tmpDir, sampleTurn(1));
+        // The session was just written. Advance "now" by > 1 hour and read.
+        const future = Date.now() + SESSION_IDLE_MS + 60_000;
+        expect(readSession(tmpDir, future)).toBeNull();
+    });
+    it("returns the session when within the idle window", () => {
+        appendTurn(tmpDir, sampleTurn(1));
+        const future = Date.now() + SESSION_IDLE_MS - 60_000;
+        expect(readSession(tmpDir, future)).not.toBeNull();
+    });
+    it("returns null when file is missing", () => {
+        expect(readSession(tmpDir)).toBeNull();
+    });
+    it("returns null when file is corrupt JSON", () => {
+        const path = join(tmpDir, ".mneme", "session.json");
+        mkdirSync(join(tmpDir, ".mneme"), { recursive: true });
+        writeFileSync(path, "{ not valid json", "utf8");
+        expect(readSession(tmpDir)).toBeNull();
+    });
+});
+describe("session — turn cap", () => {
+    it("retains only the last 20 turns when 25 are appended", () => {
+        for (let i = 1; i <= 25; i++) {
+            appendTurn(tmpDir, sampleTurn(i));
+        }
+        const s = readSession(tmpDir);
+        expect(s.turns).toHaveLength(20);
+        // Oldest 5 dropped — first remaining is turn #6.
+        expect(s.turns[0].topHashes[0]).toBe("hash6a");
+        expect(s.turns[19].topHashes[0]).toBe("hash25a");
+    });
+});
+describe("session — context building", () => {
+    it("returns an empty context for a null session", () => {
+        const ctx = buildSessionContext(null);
+        expect(ctx.recentHashes.size).toBe(0);
+        expect(ctx.recentFiles.size).toBe(0);
+        expect(ctx.recentTopics.size).toBe(0);
+    });
+    it("aggregates hashes, files, and topics from recent turns", () => {
+        appendTurn(tmpDir, {
+            at: new Date().toISOString(),
+            question: "Why does payment retry fail?",
+            topHashes: ["abc", "def"],
+            topFiles: ["src/pay.ts"],
+            confidence: "high",
+        });
+        appendTurn(tmpDir, {
+            at: new Date().toISOString(),
+            question: "How does the payment retry interact with billing?",
+            topHashes: ["def", "ghi"],
+            topFiles: ["src/bill.ts"],
+            confidence: "medium",
+        });
+        const s = readSession(tmpDir);
+        const ctx = buildSessionContext(s);
+        // Hashes union'd.
+        expect([...ctx.recentHashes].sort()).toEqual(["abc", "def", "ghi"]);
+        // Files union'd.
+        expect([...ctx.recentFiles].sort()).toEqual(["src/bill.ts", "src/pay.ts"]);
+        // "payment" appears in both questions, so its weight should be >= 2.
+        expect(ctx.recentTopics.get("payment")).toBeGreaterThanOrEqual(2);
+        expect(ctx.recentTopics.get("retry")).toBeGreaterThanOrEqual(2);
+        // Stop words must NOT make it into topics.
+        expect(ctx.recentTopics.has("the")).toBe(false);
+        expect(ctx.recentTopics.has("does")).toBe(false);
+    });
+    it("only considers the last 5 turns when building topics", () => {
+        for (let i = 1; i <= 7; i++) {
+            appendTurn(tmpDir, {
+                at: new Date(2026, 4, 1, 12, i).toISOString(),
+                question: `unique${i}word topic${i}`,
+                topHashes: [`h${i}`],
+                topFiles: [`f${i}.ts`],
+                confidence: "low",
+            });
+        }
+        const ctx = buildSessionContext(readSession(tmpDir));
+        // The first two turns' unique tokens should be evicted by the 5-turn window.
+        expect(ctx.recentTopics.has("unique1word")).toBe(false);
+        expect(ctx.recentTopics.has("unique2word")).toBe(false);
+        expect(ctx.recentTopics.has("unique7word")).toBe(true);
+    });
+});
+describe("session — clearSession", () => {
+    it("removes the file when present", () => {
+        appendTurn(tmpDir, sampleTurn(1));
+        expect(existsSync(join(tmpDir, ".mneme", "session.json"))).toBe(true);
+        clearSession(tmpDir);
+        expect(existsSync(join(tmpDir, ".mneme", "session.json"))).toBe(false);
+        expect(readSession(tmpDir)).toBeNull();
+    });
+    it("is a no-op when no session file exists", () => {
+        expect(() => clearSession(tmpDir)).not.toThrow();
+    });
+});
+describe("session — concurrent writes", () => {
+    it("never leaves the JSON file in a corrupt state", () => {
+        // Fire many appends in quick succession. Atomic-rename pattern guarantees
+        // any successful read sees a fully-written JSON document, never a partial one.
+        for (let i = 0; i < 30; i++) {
+            appendTurn(tmpDir, sampleTurn(i));
+        }
+        const path = join(tmpDir, ".mneme", "session.json");
+        const raw = readFileSync(path, "utf8");
+        // Must parse cleanly.
+        const parsed = JSON.parse(raw);
+        expect(Array.isArray(parsed.turns)).toBe(true);
+        expect(parsed.turns.length).toBeGreaterThan(0);
+        expect(parsed.turns.length).toBeLessThanOrEqual(20);
+    });
+});
+describe("session — missing repo dir", () => {
+    it("readSession returns null for a non-existent path", () => {
+        expect(readSession(join(tmpDir, "does-not-exist"))).toBeNull();
+    });
+    it("appendTurn creates .mneme dir under an existing repoRoot", () => {
+        // The repo root exists (tmpDir) but .mneme does not yet.
+        appendTurn(tmpDir, sampleTurn(1));
+        expect(existsSync(join(tmpDir, ".mneme", "session.json"))).toBe(true);
+    });
+});
+//# sourceMappingURL=session.test.js.map

package/dist/wisdom/session.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.js","sourceRoot":"","sources":["../../src/wisdom/session.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mneme-ai/core",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "Core indexing, retrieval, and graph engine for Mneme",
   "type": "module",
   "main": "./dist/index.js",