@chiligpt/memory 0.1.0

package/dist/service.js

@@ -0,0 +1,465 @@
+/**
+ * MemoryService — the public API class for @chili/memory.
+ *
+ * Wraps the session-scoped state previously held as a module-level singleton
+ * in the chili memory extension. Consumers (chili adapter, web app) instantiate
+ * one MemoryService per session and call lifecycle methods from their event handlers.
+ *
+ * Adapted for @chili/memory: no chili-internal imports. Uses IMemoryStorage,
+ * LLMCompleteFn, and MemoryBranchEntry from the package's own types.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadAllEntities, updateEntity } from "./core/entity.js";
+import { EntityIndex } from "./core/entity-index.js";
+import { writeContextNodeFromCompaction, loadAllContextNodes, updateContextNode } from "./core/context-graph.js";
+import { NarrativeCache, archiveDeadHubs, buildNarrativeSystemPromptBlock, loadAllNarrativeNodes, runNarrativeTick, updateNarrativeLayer, } from "./core/narrative.js";
+import { buildSessionStartInjection, buildPerTurnInjection, memoryEntityLookup, memoryQuery, memoryRecall, } from "./core/read-path.js";
+import { recordSessionStart, loadSessionTree, buildTreeRenderRows, renderSessionTree, } from "./core/session-tree-index.js";
+import { findUnindexedSessions, readSessionForBackfill, runBackfillIndexing } from "./core/backfill.js";
+// ---------------------------------------------------------------------------
+// Orphan detection helpers — adapted for IMemoryStorage
+// ---------------------------------------------------------------------------
+const ONE_YEAR_MS = 365 * 86_400_000;
+// ---------------------------------------------------------------------------
+// MemoryService
+// ---------------------------------------------------------------------------
+export class MemoryService {
+    storage;
+    complete;
+    cwd;
+    sessionId;
+    sessionFile;
+    parentSessionFile;
+    // Session-scoped mutable state (set during init())
+    entityIndex = new EntityIndex();
+    narrativeCache = new NarrativeCache();
+    sessionStartInjectionDone = false;
+    memoryEnabled = true;
+    backfillDone = false;
+    turnCount = 0;
+    initialized = false;
+    constructor(config) {
+        this.storage = config.storage;
+        this.complete = config.complete;
+        this.cwd = config.cwd;
+        this.sessionId = config.sessionId;
+        this.sessionFile = config.sessionFile ?? "";
+        this.parentSessionFile = config.parentSessionFile ?? null;
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle — called by the adapter from event hooks
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialise storage, build indices, and return the narrative system prompt block.
+     * Call once at session_start before any other method.
+     * Returns { systemPromptAppend } for inclusion in the session system prompt.
+     */
+    async init() {
+        // Initialise storage (create dirs, touch files)
+        await this.storage.init();
+        // Build O(1) entity index from disk (O(N) startup)
+        const allEntities = (await loadAllEntities(this.storage)).filter((n) => !n._archived);
+        this.entityIndex.build(allEntities);
+        // Load all NarrativeNodes into cache
+        const allNarratives = await loadAllNarrativeNodes(this.storage);
+        this.narrativeCache.build(allNarratives);
+        // Build BM25F index from hubs + spoke context nodes
+        try {
+            const allContextNodes = await loadAllContextNodes(this.storage);
+            this.narrativeCache.buildIndex(allContextNodes);
+        }
+        catch (err) {
+            console.error("[memory] BM25F index build error:", err instanceof Error ? err.message : String(err));
+        }
+        // Record session in persistent tree index (F-74)
+        try {
+            await recordSessionStart({
+                storage: this.storage,
+                sessionId: this.sessionId,
+                sessionFile: this.sessionFile,
+                parentSessionFile: this.parentSessionFile,
+                cwd: this.cwd,
+            });
+        }
+        catch (err) {
+            console.error("[memory] session tree index error:", err instanceof Error ? err.message : String(err));
+        }
+        // Archive dead hubs at session start (F-98)
+        try {
+            const deadCount = await archiveDeadHubs(this.storage, this.narrativeCache);
+            if (deadCount > 0) {
+                console.log(`[memory] Archived ${deadCount} dead hub(s) at session start`);
+            }
+        }
+        catch (err) {
+            console.error("[memory] dead hub detection error:", err instanceof Error ? err.message : String(err));
+        }
+        this.initialized = true;
+        // Build and return the narrative system prompt block (F-62)
+        const relevantHubs = this.narrativeCache.getHubsForContext(this.cwd, 5);
+        const totalHubCount = this.narrativeCache.size;
+        const narrativeBlock = buildNarrativeSystemPromptBlock(relevantHubs, totalHubCount);
+        return { systemPromptAppend: narrativeBlock };
+    }
+    /**
+     * Called before each agent turn (before_agent_start).
+     * Returns a system prompt injection string, or null if nothing to inject.
+     */
+    async onBeforeTurn(prompt) {
+        if (!this.initialized || !this.memoryEnabled)
+            return null;
+        const injections = [];
+        // F-97: Narrative tick every 20 turns (fire-and-forget)
+        this.turnCount++;
+        if (this.turnCount > 1 && this.turnCount % 20 === 0) {
+            runNarrativeTick(this.storage, this.narrativeCache, this.complete).catch((err) => console.error("[memory] narrative tick error:", err instanceof Error ? err.message : String(err)));
+        }
+        // F-65: Session start context retrieval (once per session)
+        if (!this.sessionStartInjectionDone) {
+            this.sessionStartInjectionDone = true;
+            const sessionBlock = await buildSessionStartInjection({
+                storage: this.storage,
+                entityIndex: this.entityIndex,
+                narrativeCache: this.narrativeCache,
+                cwd: this.cwd,
+                sessionPrompt: prompt,
+            });
+            if (sessionBlock)
+                injections.push(sessionBlock);
+        }
+        // F-66: Per-turn entity-driven injection
+        if (prompt) {
+            const perTurnBlock = await buildPerTurnInjection({
+                userMessage: prompt,
+                storage: this.storage,
+                entityIndex: this.entityIndex,
+            });
+            if (perTurnBlock)
+                injections.push(perTurnBlock);
+        }
+        return injections.length > 0 ? injections.join("\n\n") : null;
+    }
+    /**
+     * Called after each agent turn (agent_end).
+     * Runs retroactive backfill on first turn, fires-and-forgets.
+     */
+    async onAgentEnd() {
+        if (!this.initialized || this.backfillDone)
+            return;
+        this.backfillDone = true;
+        try {
+            const result = await runBackfillIndexing({
+                storage: this.storage,
+                entityIndex: this.entityIndex,
+                narrativeCache: this.narrativeCache,
+                complete: this.complete,
+                currentSessionId: this.sessionId,
+            });
+            if (result.processed > 0) {
+                console.log(`[memory] Indexed ${result.processed} past session(s) into memory.`);
+            }
+        }
+        catch (err) {
+            console.error("[memory] backfill error:", err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * Called when a compaction event fires (session_before_compact).
+     * Writes a ContextNode and updates the narrative layer.
+     */
+    async onCompaction(entries, sessionId, sessionFile, cwd) {
+        if (!this.initialized)
+            return;
+        const newNode = await writeContextNodeFromCompaction({
+            branchEntries: entries,
+            sessionId,
+            sessionFile,
+            storage: this.storage,
+            entityIndex: this.entityIndex,
+            complete: this.complete,
+            cwd,
+        });
+        if (newNode) {
+            await updateNarrativeLayer({
+                newNode,
+                storage: this.storage,
+                cache: this.narrativeCache,
+                complete: this.complete,
+            });
+        }
+    }
+    /**
+     * Called at session shutdown (session_shutdown).
+     * Performs session-close flush, dead hub archival, and orphan detection.
+     */
+    async onShutdown() {
+        if (!this.initialized)
+            return;
+        // F-73: Session-close flush — index uncompacted session entries
+        try {
+            if (this.sessionFile) {
+                const sessionData = readSessionForBackfill(this.sessionFile);
+                if (sessionData && sessionData.entries.length > 0) {
+                    const newNode = await writeContextNodeFromCompaction({
+                        branchEntries: sessionData.entries,
+                        sessionId: sessionData.sessionId,
+                        sessionFile: this.sessionFile,
+                        storage: this.storage,
+                        entityIndex: this.entityIndex,
+                        complete: this.complete,
+                        cwd: sessionData.cwd,
+                    });
+                    if (newNode) {
+                        await updateNarrativeLayer({
+                            newNode,
+                            storage: this.storage,
+                            cache: this.narrativeCache,
+                            complete: this.complete,
+                        });
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error("[memory] session flush error:", err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            // F-98: Archive dead hubs
+            try {
+                await archiveDeadHubs(this.storage, this.narrativeCache);
+            }
+            catch (err) {
+                console.error("[memory] dead hub detection error:", err instanceof Error ? err.message : String(err));
+            }
+            // F-56: Orphan detection
+            try {
+                await this.runOrphanDetection();
+            }
+            catch (err) {
+                console.error("[memory] orphan detection error:", err instanceof Error ? err.message : String(err));
+            }
+        }
+    }
+    /**
+     * Run retroactive backfill indexing for all unindexed sessions.
+     */
+    async runBackfill() {
+        if (!this.initialized)
+            return { processed: 0, skipped: 0, errors: 0, total: 0 };
+        return runBackfillIndexing({
+            storage: this.storage,
+            entityIndex: this.entityIndex,
+            narrativeCache: this.narrativeCache,
+            complete: this.complete,
+            currentSessionId: this.sessionId,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Query methods — called by tool execute callbacks and web consumers
+    // ---------------------------------------------------------------------------
+    async query(topic) {
+        if (!this.memoryEnabled)
+            return "[Memory system disabled for this session]";
+        return memoryQuery(topic, this.storage, this.entityIndex, this.narrativeCache, this.cwd, this.complete);
+    }
+    async entityLookup(name, type) {
+        if (!this.memoryEnabled)
+            return "[Memory system disabled for this session]";
+        return memoryEntityLookup(name, type, this.storage, this.entityIndex);
+    }
+    async recall(topic, options = {}) {
+        if (!this.memoryEnabled)
+            return "[Memory system disabled for this session]";
+        const fromDate = options.from_date ? new Date(options.from_date) : undefined;
+        const toDate = options.to_date ? new Date(options.to_date) : undefined;
+        return memoryRecall(topic, this.storage, this.entityIndex, this.narrativeCache, options.max_turns ?? 30, this.cwd, fromDate, toDate, this.complete);
+    }
+    // ---------------------------------------------------------------------------
+    // Toggle and status
+    // ---------------------------------------------------------------------------
+    enable() {
+        this.memoryEnabled = true;
+    }
+    disable() {
+        this.memoryEnabled = false;
+    }
+    get isEnabled() {
+        return this.memoryEnabled;
+    }
+    get stats() {
+        return {
+            hubs: this.narrativeCache.size,
+            entities: this.entityIndex.size,
+            contextNodes: 0, // populated lazily — callers can call query for count
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Session tree view (used by /memory tree)
+    // ---------------------------------------------------------------------------
+    async renderTree(currentSessionId) {
+        const index = await loadSessionTree(this.storage);
+        const contextNodes = await this.storage.readAll("context");
+        const contextNodeSessions = new Set(contextNodes.map((n) => n.sessionId));
+        const rows = buildTreeRenderRows(index, currentSessionId, contextNodeSessions);
+        return renderSessionTree(rows);
+    }
+    /**
+     * Count of unindexed sessions. Returned from init() as a hint to the caller
+     * (the chili adapter can then notify the user).
+     */
+    async countUnindexed() {
+        try {
+            const unindexed = await findUnindexedSessions(this.storage, this.sessionId);
+            return unindexed.length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Skill file management (called from resources_discover)
+    // ---------------------------------------------------------------------------
+    /**
+     * Write SKILL.md files to the extension storage dir and return their paths.
+     * Called once per session from the resources_discover event handler.
+     */
+    getSkillPaths(storageDir) {
+        const skillsBase = join(storageDir, "skills");
+        const memoryQueryDir = join(skillsBase, "memory-query");
+        const memoryLookupDir = join(skillsBase, "memory-lookup");
+        const memoryRecallDir = join(skillsBase, "memory-recall");
+        mkdirSync(memoryQueryDir, { recursive: true });
+        mkdirSync(memoryLookupDir, { recursive: true });
+        mkdirSync(memoryRecallDir, { recursive: true });
+        writeFileSync(join(memoryQueryDir, "SKILL.md"), SKILL_MEMORY_QUERY, "utf-8");
+        writeFileSync(join(memoryLookupDir, "SKILL.md"), SKILL_MEMORY_LOOKUP, "utf-8");
+        writeFileSync(join(memoryRecallDir, "SKILL.md"), SKILL_MEMORY_RECALL, "utf-8");
+        return [memoryQueryDir, memoryLookupDir, memoryRecallDir];
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async runOrphanDetection() {
+        const now = Date.now();
+        const archivedIds = new Set();
+        for (const node of this.entityIndex.values()) {
+            if (now - node.lastReferencedAt > ONE_YEAR_MS) {
+                await this.storage.archive("entities-archive", node);
+                await updateEntity(this.storage, node.id, { _archived: true });
+                archivedIds.add(node.id);
+            }
+        }
+        if (archivedIds.size === 0)
+            return;
+        const contextNodes = await this.storage.readAll("context");
+        for (const ctx of contextNodes) {
+            if (!ctx.entityPointerIds?.length)
+                continue;
+            if (ctx.allEntitiesArchived)
+                continue;
+            const allArchived = ctx.entityPointerIds.every((id) => archivedIds.has(id));
+            if (allArchived) {
+                await updateContextNode(this.storage, ctx.id, { allEntitiesArchived: true });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Skill content strings (F-70, F-71, F-81/F-82)
+// ---------------------------------------------------------------------------
+const SKILL_MEMORY_QUERY = `---
+name: memory-query
+description: Broad memory context recall — loads narrative hub summaries, all linked context and entity nodes, with optional session-level detail. Use when user wants full context on a topic area.
+---
+
+# Memory Query Protocol
+
+Use this skill when the user asks about past work, ongoing themes, or broad topic areas stored in memory.
+
+## Three-Step Traversal Protocol
+
+### Step 1 — Narrative Match
+Call \`memory_query(topic)\` with the user's topic. The tool matches narrative hub topics (case-insensitive containment) and returns hub summaries with linked context node summaries. Report all matching hubs and their summaries to orient the user.
+
+### Step 2 — Context Node Load
+The \`memory_query\` response includes context node summaries for each matched hub. For each context node:
+- Check the health annotation: nodes marked \`[STALE: N degraded, M deprecated entities]\` should be flagged.
+- Note the session ID, date, and working directory fields for provenance.
+- Both sides of a supersession pair are always surfaced — present both; never present only the superseding node.
+
+### Step 3 — Entity Investigation (on-demand only)
+**Do not automatically call \`memory_entity_lookup\` for every entity in the result.** Only call it when:
+- The user explicitly asks about the health, history, or validity of a specific named entity.
+- An entity appears in a stale context node and the user wants to know if it is still relevant.
+
+When called, \`memory_entity_lookup(name, type)\` returns:
+- Current validity score and label (trusted / uncertain / degraded / deprecated).
+- All context nodes that reference the entity, newest first.
+
+Explicitly warn the user when any looked-up entity has validity < 0.3 (degraded or deprecated), citing the entity name and score.
+
+### Layer 1 Traversal (on-demand only)
+**Do not access Layer 1 automatically.** When the user explicitly requests session-level detail or conversation excerpts, use \`memory_recall(topic)\` — it resolves the session file internally and returns conversation turns without requiring manual tree reads or bash greps.
+
+### Response Format
+Present results in this order:
+1. Hub summary (title, topics, summary, session count).
+2. Context node summaries, newest first (date, user context, agent context, entity health table).
+3. Entity detail, only if explicitly requested via Step 3.
+4. Session conversation turns, only if explicitly requested (use \`memory_recall\`).
+`;
+const SKILL_MEMORY_LOOKUP = `---
+name: memory-lookup
+description: Pinpoint session-level memory retrieval — returns the actual conversation turns from the best matching session. Use when user asks about a specific past exchange or decision.
+---
+
+# Memory Lookup Protocol
+
+Use this skill when the user asks about a specific past conversation, decision, or exchange — not just a topic area. This skill always retrieves Layer 1 session turns. Use \`/memory-query\` when the user wants breadth-first topic recall without seeing the raw conversation.
+
+## Two-Step Retrieval Protocol
+
+### Step 1 — Recall
+Call \`memory_recall(topic)\` with the user's topic. This single tool returns:
+- Matching narrative hub context (session ID, date, user context, agent context, entity health).
+- The actual conversation turns from the matched session JSONL.
+
+The tool resolves the session file path internally — do **not** manually grep for session paths or read \`layer0-session-tree.jsonl\`. If the tool reports "Session file not found", present the context node summary as the best available record.
+
+If the user provides a session ID directly (not a topic), call \`memory_query(sessionId)\` first to locate the context node, then call \`memory_recall\` with one of the context node's topics.
+
+### Step 2 — Entity Lookup (only when explicitly needed)
+Call \`memory_entity_lookup(name, type)\` **only** when the user explicitly asks about a specific named artifact — a file path, function name, module, person, or architectural decision. Do **not** call it for topic phrases like "gardening", "python", or "auth flow" — those are topics for \`memory_recall\`, not entities.
+
+When in doubt: if the user said a noun that could be a filename or proper name, use entity lookup. If they described a subject area or past conversation, use \`memory_recall\`.
+
+## Supersession
+Context nodes marked \`[SUPERSEDES: <sessionId>]\` indicate the retrieved session updates an earlier one. Always surface both sides of a supersession pair so the user can see the evolution.
+`;
+const SKILL_MEMORY_RECALL = `---
+name: memory-recall
+description: Unified session recall tool — retrieves context node summary and conversation turns in one call. Agent-callable via memory_recall(topic). No manual file resolution needed.
+---
+
+# memory_recall Tool Reference
+
+\`memory_recall\` is an agent tool (not a user slash command). It is the primary retrieval primitive for \`/memory-lookup\`.
+
+## What it does
+Combines narrative hub matching, context node load, and Layer 1 JSONL reading into a single tool call. Returns the context node summary (session ID, date, entities, health) plus the actual conversation turns from the matched session.
+
+## When to use
+- User asks about a specific past conversation or decision → call \`memory_recall(topic)\`
+- Do NOT manually grep for session paths or read \`layer0-session-tree.jsonl\` — the tool resolves these internally via the \`sessionFile\` field (F-75) or session tree index fallback.
+
+## Parameters
+- \`topic\` (string) — the subject area or keyword to match against narrative hubs
+- \`max_turns\` (number, optional) — cap on conversation turns returned (default 30, max 200)
+
+## Session file resolution order
+1. Uses \`sessionFile\` field on the context node directly (F-75 — present on all modern nodes).
+2. Falls back to session tree index lookup when \`sessionFile\` is absent (pre-F-75 nodes).
+3. Reports "Not available" if both fail — presents context node summary as best available record.
+`;
+//# sourceMappingURL=service.js.map

package/dist/storage/adapter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * IMemoryStorage — the storage adapter interface for @chili/memory.
+ *
+ * Decouples all domain logic from storage concerns. Implementations:
+ *   - JsonlMemoryStorage  (Node.js, file-per-collection, proper-lockfile)
+ *   - InMemoryStorage     (tests and Phase 1 web validation, no persistence)
+ *   - PostgresMemoryStorage (web, defined by the consuming repo against this interface)
+ *
+ * readAll() is async throughout — required for Postgres compatibility.
+ * JsonlMemoryStorage wraps synchronous readFileSync in Promise.resolve() at
+ * zero overhead while satisfying the interface for all consumers.
+ */
+/**
+ * Active collection identifiers. Each maps to a distinct storage location
+ * (file, table, or in-memory map) in the implementing adapter.
+ */
+export type MemoryCollection = "context" | "entities" | "narratives" | "session-tree";
+/**
+ * Archive collection identifiers. Records moved here are never deleted —
+ * consistent with the Layer 1 immutability principle.
+ */
+export type MemoryArchiveCollection = "entities-archive" | "narratives-archive";
+export interface IMemoryStorage {
+    /**
+     * Initialise storage — create directories, tables, or in-memory maps.
+     * Must be called once before any other method.
+     */
+    init(): Promise<void>;
+    /**
+     * Append a new record to a collection.
+     * The record must have a stable string `id` field.
+     */
+    append<T extends {
+        id: string;
+    }>(collection: MemoryCollection, record: T): Promise<void>;
+    /**
+     * Read all active records from a collection, in insertion order.
+     *
+     * Async throughout so Postgres and other async adapters satisfy the same
+     * interface. JsonlMemoryStorage wraps readFileSync in Promise.resolve().
+     */
+    readAll<T>(collection: MemoryCollection): Promise<T[]>;
+    /**
+     * Apply a partial patch to the record matching `id` in `collection`.
+     * Fields not included in `patch` are left unchanged.
+     * No-op when `id` is not found.
+     */
+    update<T extends {
+        id: string;
+    }>(collection: MemoryCollection, id: string, patch: Partial<T>): Promise<void>;
+    /**
+     * Move a record to the archive collection.
+     * Implementations must not delete the original — archive is append-only
+     * cold storage. The caller is responsible for marking the active record
+     * with `_archived: true` via `update()` if needed.
+     */
+    archive<T extends {
+        id: string;
+    }>(collection: MemoryArchiveCollection, record: T): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/storage/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/storage/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACzB,SAAS,GACT,UAAU,GACV,YAAY,GACZ,cAAc,CAAC;AAElB;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAChC,kBAAkB,GAClB,oBAAoB,CAAC;AAMxB,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;OAGG;IACH,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzF;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvD;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAC9B,UAAU,EAAE,gBAAgB,EAC5B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GACf,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAC/B,UAAU,EAAE,uBAAuB,EACnC,MAAM,EAAE,CAAC,GACP,OAAO,CAAC,IAAI,CAAC,CAAC;CACjB","sourcesContent":["/**\n * IMemoryStorage — the storage adapter interface for @chili/memory.\n *\n * Decouples all domain logic from storage concerns. Implementations:\n *   - JsonlMemoryStorage  (Node.js, file-per-collection, proper-lockfile)\n *   - InMemoryStorage     (tests and Phase 1 web validation, no persistence)\n *   - PostgresMemoryStorage (web, defined by the consuming repo against this interface)\n *\n * readAll() is async throughout — required for Postgres compatibility.\n * JsonlMemoryStorage wraps synchronous readFileSync in Promise.resolve() at\n * zero overhead while satisfying the interface for all consumers.\n */\n\n// ---------------------------------------------------------------------------\n// Collection names\n// ---------------------------------------------------------------------------\n\n/**\n * Active collection identifiers. Each maps to a distinct storage location\n * (file, table, or in-memory map) in the implementing adapter.\n */\nexport type MemoryCollection =\n\t| \"context\"        // ContextNode records  — layer2-context.jsonl\n\t| \"entities\"       // EntityNode records   — layer2-entity.jsonl\n\t| \"narratives\"     // NarrativeNode records — layer3-narrative.jsonl\n\t| \"session-tree\";  // SessionTreeEntry records — layer0-session-tree.jsonl\n\n/**\n * Archive collection identifiers. Records moved here are never deleted —\n * consistent with the Layer 1 immutability principle.\n */\nexport type MemoryArchiveCollection =\n\t| \"entities-archive\"   // Orphaned EntityNodes (>12 months unreferenced)\n\t| \"narratives-archive\"; // LRU-evicted NarrativeNodes (beyond 20-hub limit)\n\n// ---------------------------------------------------------------------------\n// Adapter interface\n// ---------------------------------------------------------------------------\n\nexport interface IMemoryStorage {\n\t/**\n\t * Initialise storage — create directories, tables, or in-memory maps.\n\t * Must be called once before any other method.\n\t */\n\tinit(): Promise<void>;\n\n\t/**\n\t * Append a new record to a collection.\n\t * The record must have a stable string `id` field.\n\t */\n\tappend<T extends { id: string }>(collection: MemoryCollection, record: T): Promise<void>;\n\n\t/**\n\t * Read all active records from a collection, in insertion order.\n\t *\n\t * Async throughout so Postgres and other async adapters satisfy the same\n\t * interface. JsonlMemoryStorage wraps readFileSync in Promise.resolve().\n\t */\n\treadAll<T>(collection: MemoryCollection): Promise<T[]>;\n\n\t/**\n\t * Apply a partial patch to the record matching `id` in `collection`.\n\t * Fields not included in `patch` are left unchanged.\n\t * No-op when `id` is not found.\n\t */\n\tupdate<T extends { id: string }>(\n\t\tcollection: MemoryCollection,\n\t\tid: string,\n\t\tpatch: Partial<T>,\n\t): Promise<void>;\n\n\t/**\n\t * Move a record to the archive collection.\n\t * Implementations must not delete the original — archive is append-only\n\t * cold storage. The caller is responsible for marking the active record\n\t * with `_archived: true` via `update()` if needed.\n\t */\n\tarchive<T extends { id: string }>(\n\t\tcollection: MemoryArchiveCollection,\n\t\trecord: T,\n\t): Promise<void>;\n}\n"]}

package/dist/storage/adapter.js

@@ -0,0 +1,14 @@
+/**
+ * IMemoryStorage — the storage adapter interface for @chili/memory.
+ *
+ * Decouples all domain logic from storage concerns. Implementations:
+ *   - JsonlMemoryStorage  (Node.js, file-per-collection, proper-lockfile)
+ *   - InMemoryStorage     (tests and Phase 1 web validation, no persistence)
+ *   - PostgresMemoryStorage (web, defined by the consuming repo against this interface)
+ *
+ * readAll() is async throughout — required for Postgres compatibility.
+ * JsonlMemoryStorage wraps synchronous readFileSync in Promise.resolve() at
+ * zero overhead while satisfying the interface for all consumers.
+ */
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/storage/file-utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read all records from an arbitrary JSONL file path.
+ * Returns an empty array if the file does not exist or is empty.
+ * Malformed lines are silently skipped.
+ */
+export declare function readJsonlFile<T>(filePath: string): T[];
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/storage/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/storage/file-utils.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,EAAE,CAmBtD","sourcesContent":["/**\n * Thin Node.js utility for reading arbitrary JSONL files.\n *\n * NOT part of IMemoryStorage — this is used only by readSessionForBackfill()\n * to read existing session JSONL files that are not managed by the storage\n * adapter. The web consumer would never call readSessionForBackfill (it has\n * no session JSONL files on disk).\n */\nimport { readFileSync } from \"node:fs\";\n\n/**\n * Read all records from an arbitrary JSONL file path.\n * Returns an empty array if the file does not exist or is empty.\n * Malformed lines are silently skipped.\n */\nexport function readJsonlFile<T>(filePath: string): T[] {\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(filePath, \"utf-8\");\n\t} catch {\n\t\treturn [];\n\t}\n\n\tconst records: T[] = [];\n\tfor (const line of raw.split(\"\\n\")) {\n\t\tconst trimmed = line.trim();\n\t\tif (!trimmed) continue;\n\t\ttry {\n\t\t\trecords.push(JSON.parse(trimmed) as T);\n\t\t} catch {\n\t\t\t// Skip malformed lines\n\t\t}\n\t}\n\treturn records;\n}\n"]}

package/dist/storage/file-utils.js

@@ -0,0 +1,37 @@
+/**
+ * Thin Node.js utility for reading arbitrary JSONL files.
+ *
+ * NOT part of IMemoryStorage — this is used only by readSessionForBackfill()
+ * to read existing session JSONL files that are not managed by the storage
+ * adapter. The web consumer would never call readSessionForBackfill (it has
+ * no session JSONL files on disk).
+ */
+import { readFileSync } from "node:fs";
+/**
+ * Read all records from an arbitrary JSONL file path.
+ * Returns an empty array if the file does not exist or is empty.
+ * Malformed lines are silently skipped.
+ */
+export function readJsonlFile(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            records.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return records;
+}
+//# sourceMappingURL=file-utils.js.map

package/dist/storage/in-memory-entry.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @chili/memory/storage/in-memory — direct sub-entry point for InMemoryStorage.
+ */
+export { InMemoryStorage } from "./in-memory.js";
+//# sourceMappingURL=in-memory-entry.d.ts.map

package/dist/storage/in-memory-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-entry.d.ts","sourceRoot":"","sources":["../../src/storage/in-memory-entry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * @chili/memory/storage/in-memory — direct sub-entry point for InMemoryStorage.\n */\nexport { InMemoryStorage } from \"./in-memory.js\";\n"]}

package/dist/storage/in-memory-entry.js

@@ -0,0 +1,5 @@
+/**
+ * @chili/memory/storage/in-memory — direct sub-entry point for InMemoryStorage.
+ */
+export { InMemoryStorage } from "./in-memory.js";
+//# sourceMappingURL=in-memory-entry.js.map

package/dist/storage/in-memory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * InMemoryStorage — IMemoryStorage implementation backed by in-memory Maps.
+ *
+ * No disk I/O. No locking. All methods return immediately resolved promises.
+ * Used for:
+ *   - Unit tests (replacing temp-dir JSONL setup with fast in-memory fixtures)
+ *   - Phase 1 web validation (confirms MemoryService lifecycle works without Postgres)
+ *
+ * Records are stored in insertion order per collection. readAll() returns
+ * records in insertion order, matching the JSONL file behaviour.
+ */
+import type { IMemoryStorage, MemoryCollection, MemoryArchiveCollection } from "./adapter.js";
+export declare class InMemoryStorage implements IMemoryStorage {
+    private readonly store;
+    init(): Promise<void>;
+    append<T extends {
+        id: string;
+    }>(collection: MemoryCollection, record: T): Promise<void>;
+    readAll<T>(collection: MemoryCollection): Promise<T[]>;
+    update<T extends {
+        id: string;
+    }>(collection: MemoryCollection, id: string, patch: Partial<T>): Promise<void>;
+    archive<T extends {
+        id: string;
+    }>(collection: MemoryArchiveCollection, record: T): Promise<void>;
+    /**
+     * Reset all collections — useful between tests.
+     * Not part of IMemoryStorage interface; test-only utility.
+     */
+    clear(): void;
+    /**
+     * Read from archive collections — not part of IMemoryStorage but useful for
+     * asserting archive operations in tests.
+     */
+    readArchive<T>(collection: MemoryArchiveCollection): T[];
+}
+//# sourceMappingURL=in-memory.d.ts.map

package/dist/storage/in-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../src/storage/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE9F,qBAAa,eAAgB,YAAW,cAAc;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IAEhD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAEK,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7F;IAEK,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAE3D;IAEK,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACpC,UAAU,EAAE,gBAAgB,EAC5B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;IAEK,OAAO,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACrC,UAAU,EAAE,uBAAuB,EACnC,MAAM,EAAE,CAAC,GACP,OAAO,CAAC,IAAI,CAAC,CAIf;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAEZ;IAED;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,uBAAuB,GAAG,CAAC,EAAE,CAEvD;CACD","sourcesContent":["/**\n * InMemoryStorage — IMemoryStorage implementation backed by in-memory Maps.\n *\n * No disk I/O. No locking. All methods return immediately resolved promises.\n * Used for:\n *   - Unit tests (replacing temp-dir JSONL setup with fast in-memory fixtures)\n *   - Phase 1 web validation (confirms MemoryService lifecycle works without Postgres)\n *\n * Records are stored in insertion order per collection. readAll() returns\n * records in insertion order, matching the JSONL file behaviour.\n */\n\nimport type { IMemoryStorage, MemoryCollection, MemoryArchiveCollection } from \"./adapter.js\";\n\nexport class InMemoryStorage implements IMemoryStorage {\n\tprivate readonly store = new Map<string, unknown[]>();\n\n\tasync init(): Promise<void> {\n\t\t// Nothing to initialise for in-memory storage.\n\t}\n\n\tasync append<T extends { id: string }>(collection: MemoryCollection, record: T): Promise<void> {\n\t\tconst existing = this.store.get(collection) ?? [];\n\t\texisting.push(record);\n\t\tthis.store.set(collection, existing);\n\t}\n\n\tasync readAll<T>(collection: MemoryCollection): Promise<T[]> {\n\t\treturn (this.store.get(collection) ?? []) as T[];\n\t}\n\n\tasync update<T extends { id: string }>(\n\t\tcollection: MemoryCollection,\n\t\tid: string,\n\t\tpatch: Partial<T>,\n\t): Promise<void> {\n\t\tconst records = this.store.get(collection);\n\t\tif (!records) return;\n\t\tconst idx = records.findIndex((r) => (r as { id?: string }).id === id);\n\t\tif (idx === -1) return;\n\t\trecords[idx] = { ...(records[idx] as object), ...patch };\n\t}\n\n\tasync archive<T extends { id: string }>(\n\t\tcollection: MemoryArchiveCollection,\n\t\trecord: T,\n\t): Promise<void> {\n\t\tconst existing = this.store.get(collection) ?? [];\n\t\texisting.push(record);\n\t\tthis.store.set(collection, existing);\n\t}\n\n\t/**\n\t * Reset all collections — useful between tests.\n\t * Not part of IMemoryStorage interface; test-only utility.\n\t */\n\tclear(): void {\n\t\tthis.store.clear();\n\t}\n\n\t/**\n\t * Read from archive collections — not part of IMemoryStorage but useful for\n\t * asserting archive operations in tests.\n\t */\n\treadArchive<T>(collection: MemoryArchiveCollection): T[] {\n\t\treturn (this.store.get(collection) ?? []) as T[];\n\t}\n}\n"]}