@aexol/spectral 0.4.12 → 0.6.0

package/dist/commands/serve.js

@@ -231,12 +231,13 @@ export async function runServe(opts = {}) {
     // (the backend is the only producer and is exercised by tests).
     relay.on("frame", (frame) => {
         if (frame.kind === "rest_request") {
-            const response = handleRestRequest(frame, {
+            void handleRestRequest(frame, {
                 store,
                 manager,
                 publishMetaEvent: deferredPublishMetaEvent,
+            }).then((response) => {
+                relay.send(response);
             });
-            relay.send(response);
             return;
         }
         if (frame.kind === "client_message") {

package/dist/memory/branch.js

@@ -1,12 +1,19 @@
-import { OBSERVATION_CUSTOM_TYPE, isObservationEntryData, isReflectionRecord, isSupportedMemoryDetails, } from "./types.js";
+import { OBSERVATION_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, isObservationEntryData, isReflectionRecord, isRestoredMemorySnapshot, isSupportedMemoryDetails, } from "./types.js";
+import { sourceEntryReferenceIds } from "./serialize.js";
 import { estimateEntryTokens } from "./tokens.js";
-const RAW_TYPES = new Set(["message", "custom_message", "branch_summary"]);
 export function isSourceEntry(entry) {
-    return RAW_TYPES.has(entry.type);
+    if (entry.type === "message" || entry.type === "branch_summary")
+        return true;
+    if (entry.type !== "custom_message")
+        return false;
+    return entry.customType !== OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE;
 }
 function isObservationEntry(entry) {
     return entry.type === "custom" && entry.customType === OBSERVATION_CUSTOM_TYPE;
 }
+function isRestoredSnapshotEntry(entry) {
+    return entry.type === "custom" && entry.customType === OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE;
+}
 export function findLastCompactionIndex(entries) {
     for (let i = entries.length - 1; i >= 0; i--) {
         if (entries[i].type === "compaction")
@@ -31,16 +38,43 @@ export function lastObservationCoverEndIdx(entries) {
     }
     return maxIdx;
 }
+function getLatestRestoredSnapshot(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (!isRestoredSnapshotEntry(entry))
+            continue;
+        if (!isRestoredMemorySnapshot(entry.data))
+            continue;
+        return entry.data;
+    }
+    return undefined;
+}
 function rawTokensFromIndex(entries, startIndex) {
     let total = 0;
     for (let i = Math.max(0, startIndex); i < entries.length; i++) {
-        if (RAW_TYPES.has(entries[i].type))
+        if (isSourceEntry(entries[i]))
             total += estimateEntryTokens(entries[i]);
     }
     return total;
 }
+function branchIndexAfterCoveredSourceCount(entries, coveredSourceCount) {
+    if (coveredSourceCount <= 0)
+        return 0;
+    let seen = 0;
+    for (let i = 0; i < entries.length; i++) {
+        if (!isSourceEntry(entries[i]))
+            continue;
+        seen += 1;
+        if (seen >= coveredSourceCount)
+            return i + 1;
+    }
+    return entries.length;
+}
 export function rawTokensSinceLastBound(entries) {
-    return rawTokensFromIndex(entries, lastObservationCoverEndIdx(entries) + 1);
+    const coveredByLiveObservation = lastObservationCoverEndIdx(entries) + 1;
+    const restoredSnapshot = getLatestRestoredSnapshot(entries);
+    const coveredBySnapshot = branchIndexAfterCoveredSourceCount(entries, restoredSnapshot?.coveredSourceCount ?? 0);
+    return rawTokensFromIndex(entries, Math.max(coveredByLiveObservation, coveredBySnapshot));
 }
 export function rawTokensSinceLastCompaction(entries) {
     const compactionIdx = findLastCompactionIndex(entries);
@@ -62,7 +96,7 @@ function liveTailStartIndex(entries) {
 }
 export function firstRawIdAfter(entries, afterIndex) {
     for (let i = Math.max(0, afterIndex + 1); i < entries.length; i++) {
-        if (RAW_TYPES.has(entries[i].type))
+        if (isSourceEntry(entries[i]))
             return entries[i].id;
     }
     return undefined;
@@ -74,7 +108,7 @@ export function gapRawEntries(entries, newFirstKeptEntryId) {
         return [];
     const result = [];
     for (let i = lastBoundIdx + 1; i < newKeptIdx; i++) {
-        if (RAW_TYPES.has(entries[i].type))
+        if (isSourceEntry(entries[i]))
             result.push(entries[i]);
     }
     return result;
@@ -111,49 +145,65 @@ function collectIndexedObservations(entries) {
 function observationKey(observation) {
     return `${observation.observationEntryId}:${observation.observationRecordIndex}`;
 }
-function resolveSourceEntries(entries, sourceEntryIds) {
+function sourceEntryMatchesRequestedId(entry, requested) {
+    if (!isSourceEntry(entry))
+        return false;
+    if (entry.id === requested)
+        return true;
+    return sourceEntryReferenceIds(entry).includes(requested);
+}
+function buildSourceEntryResolution(entries, sourceEntryIds) {
     const requested = uniqueIds(sourceEntryIds);
-    const requestedSet = new Set(requested);
-    const entriesById = new Map(entries.map((entry) => [entry.id, entry]));
-    const missingSourceEntryIds = requested.filter((id) => !entriesById.has(id));
-    const nonSourceEntryIds = requested.filter((id) => {
-        const entry = entriesById.get(id);
-        return entry !== undefined && !isSourceEntry(entry);
-    });
-    if (missingSourceEntryIds.length > 0 || nonSourceEntryIds.length > 0) {
+    const matchedEntries = new Map();
+    for (const entry of entries) {
+        for (const requestedId of requested) {
+            if (!sourceEntryMatchesRequestedId(entry, requestedId))
+                continue;
+            matchedEntries.set(entry.id, entry);
+        }
+    }
+    const missingSourceEntryIds = [];
+    const nonSourceEntryIds = [];
+    for (const requestedId of requested) {
+        const directEntry = entries.find((entry) => entry.id === requestedId);
+        if (directEntry && !isSourceEntry(directEntry)) {
+            nonSourceEntryIds.push(requestedId);
+            continue;
+        }
+        const matched = entries.some((entry) => sourceEntryMatchesRequestedId(entry, requestedId));
+        if (!matched)
+            missingSourceEntryIds.push(requestedId);
+    }
+    const sourceEntries = entries.filter((entry) => matchedEntries.has(entry.id) && isSourceEntry(entry));
+    return { requested, sourceEntries, missingSourceEntryIds, nonSourceEntryIds };
+}
+function resolveSourceEntries(entries, sourceEntryIds) {
+    const resolved = buildSourceEntryResolution(entries, sourceEntryIds);
+    if (resolved.missingSourceEntryIds.length > 0 || resolved.nonSourceEntryIds.length > 0) {
         return {
             status: "source_unavailable",
-            sourceEntryIds: requested,
+            sourceEntryIds: resolved.requested,
             sourceEntries: [],
-            missingSourceEntryIds,
-            nonSourceEntryIds,
+            missingSourceEntryIds: resolved.missingSourceEntryIds,
+            nonSourceEntryIds: resolved.nonSourceEntryIds,
         };
     }
-    const sourceEntries = entries.filter((entry) => requestedSet.has(entry.id));
     return {
         status: "ok",
-        sourceEntryIds: sourceEntries.map((entry) => entry.id),
-        sourceEntries,
+        sourceEntryIds: resolved.requested,
+        sourceEntries: resolved.sourceEntries,
         missingSourceEntryIds: [],
         nonSourceEntryIds: [],
     };
 }
 function resolveSourceEntriesPartial(entries, sourceEntryIds) {
-    const requested = uniqueIds(sourceEntryIds);
-    const requestedSet = new Set(requested);
-    const entriesById = new Map(entries.map((entry) => [entry.id, entry]));
-    const missingSourceEntryIds = requested.filter((id) => !entriesById.has(id));
-    const nonSourceEntryIds = requested.filter((id) => {
-        const entry = entriesById.get(id);
-        return entry !== undefined && !isSourceEntry(entry);
-    });
-    const sourceEntries = entries.filter((entry) => requestedSet.has(entry.id) && isSourceEntry(entry));
+    const resolved = buildSourceEntryResolution(entries, sourceEntryIds);
     return {
-        status: missingSourceEntryIds.length > 0 || nonSourceEntryIds.length > 0 ? "source_unavailable" : "ok",
-        sourceEntryIds: requested,
-        sourceEntries,
-        missingSourceEntryIds,
-        nonSourceEntryIds,
+        status: resolved.missingSourceEntryIds.length > 0 || resolved.nonSourceEntryIds.length > 0 ? "source_unavailable" : "ok",
+        sourceEntryIds: resolved.requested,
+        sourceEntries: resolved.sourceEntries,
+        missingSourceEntryIds: resolved.missingSourceEntryIds,
+        nonSourceEntryIds: resolved.nonSourceEntryIds,
     };
 }
 function memoryObservationFromIndexed(entries, indexed) {
@@ -243,10 +293,12 @@ export function recallObservationSources(entries, observationId) {
 }
 function getPriorMemoryDetails(entries) {
     const idx = findLastCompactionIndex(entries);
-    if (idx === -1)
-        return undefined;
-    const details = entries[idx].details;
-    return isSupportedMemoryDetails(details) ? details : undefined;
+    if (idx !== -1) {
+        const details = entries[idx].details;
+        if (isSupportedMemoryDetails(details))
+            return details;
+    }
+    return getLatestRestoredSnapshot(entries)?.details;
 }
 export function recallMemorySources(entries, memoryId) {
     const indexedObservations = collectIndexedObservations(entries);
@@ -371,9 +423,10 @@ function collectObservationsPendingNextCompaction(entries) {
     for (let i = 0; i < entries.length; i++)
         idToIdx.set(entries[i].id, i);
     const priorCompactionIdx = findLastCompactionIndex(entries);
-    let thresholdIdx;
+    const restoredSnapshot = getLatestRestoredSnapshot(entries);
+    let thresholdStartIdx;
     if (priorCompactionIdx === -1) {
-        thresholdIdx = -1;
+        thresholdStartIdx = branchIndexAfterCoveredSourceCount(entries, restoredSnapshot?.coveredSourceCount ?? 0);
     }
     else {
         const priorFirstKept = entries[priorCompactionIdx].firstKeptEntryId;
@@ -382,7 +435,7 @@ function collectObservationsPendingNextCompaction(entries) {
         const idx = idToIdx.get(priorFirstKept);
         if (idx === undefined)
             throw new Error(`prior firstKeptEntryId "${priorFirstKept}" not found in entries`);
-        thresholdIdx = idx;
+        thresholdStartIdx = idx;
     }
     const result = [];
     for (const entry of entries) {
@@ -393,7 +446,7 @@ function collectObservationsPendingNextCompaction(entries) {
         const fromIdx = idToIdx.get(entry.data.coversFromId);
         if (fromIdx === undefined)
             continue;
-        if (fromIdx >= thresholdIdx)
+        if (fromIdx >= thresholdStartIdx)
             result.push(entry.data);
     }
     return result;

package/dist/memory/serialize.js

@@ -1,3 +1,4 @@
+import { hashId } from "./ids.js";
 function pad(n) {
     return n.toString().padStart(2, "0");
 }
@@ -141,9 +142,44 @@ export function serializeBranchEntries(entries) {
     }
     return blocks.join("\n\n");
 }
+export const DURABLE_SOURCE_ENTRY_ID_PREFIX = "srcv1:";
 function isSourceRenderableEntry(entry) {
     return entry.type === "message" || entry.type === "custom_message" || entry.type === "branch_summary";
 }
+function sourceTimestampSignature(entry) {
+    if (entry.type === "message" && entry.message && typeof entry.message === "object") {
+        const msg = entry.message;
+        if (msg.timestamp !== undefined)
+            return String(msg.timestamp);
+    }
+    if (entry.timestamp !== undefined)
+        return String(entry.timestamp);
+    return "";
+}
+export function durableSourceEntryId(entry) {
+    if (!isSourceRenderableEntry(entry))
+        return undefined;
+    const rendered = serializeBranchEntries([entry]);
+    if (!rendered.trim())
+        return undefined;
+    const fingerprint = [
+        "source-v1",
+        `type:${entry.type}`,
+        `customType:${entry.customType ?? ""}`,
+        `timestamp:${sourceTimestampSignature(entry)}`,
+        rendered,
+    ].join("\n");
+    return `${DURABLE_SOURCE_ENTRY_ID_PREFIX}${hashId(fingerprint)}`;
+}
+export function sourceEntryReferenceIds(entry) {
+    const refs = [];
+    if (entry.id)
+        refs.push(entry.id);
+    const durableId = durableSourceEntryId(entry);
+    if (durableId && durableId !== entry.id)
+        refs.push(durableId);
+    return refs;
+}
 export function serializeSourceAddressedBranchEntries(entries) {
     const blocks = [];
     const sourceEntryIds = [];
@@ -153,8 +189,9 @@ export function serializeSourceAddressedBranchEntries(entries) {
         const rendered = serializeBranchEntries([entry]);
         if (!rendered.trim())
             continue;
-        sourceEntryIds.push(entry.id);
-        blocks.push(`[Source entry id: ${entry.id}]\n${rendered}`);
+        const sourceEntryId = durableSourceEntryId(entry) ?? entry.id;
+        sourceEntryIds.push(sourceEntryId);
+        blocks.push(`[Source entry id: ${sourceEntryId}]\n${rendered}`);
     }
     return { text: blocks.join("\n\n"), sourceEntryIds };
 }

package/dist/memory/types.js

@@ -1,4 +1,6 @@
 export const OBSERVATION_CUSTOM_TYPE = "om.observation";
+export const OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE = "om.snapshot";
+export const OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE = "om.snapshot.context";
 export const RELEVANCE_VALUES = ["low", "medium", "high", "critical"];
 export const MEMORY_ID_PATTERN = /^[a-f0-9]{12}$/;
 function isRelevance(v) {
@@ -93,3 +95,15 @@ export function isObservationEntryData(d) {
         typeof o.coversUpToId === "string" &&
         typeof o.tokenCount === "number");
 }
+export function isRestoredMemorySnapshot(d) {
+    if (!d || typeof d !== "object")
+        return false;
+    const o = d;
+    return (o.type === "observational-memory-snapshot" &&
+        o.version === 1 &&
+        typeof o.coveredSourceCount === "number" &&
+        Number.isInteger(o.coveredSourceCount) &&
+        o.coveredSourceCount >= 0 &&
+        typeof o.summary === "string" &&
+        isSupportedMemoryDetails(o.details));
+}

package/dist/relay/dispatcher.js

@@ -41,7 +41,7 @@
 import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
 import { handlePathAutocomplete } from "../server/handlers/paths-autocomplete.js";
 import { handleCreateProject, handleDeleteProject, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
-import { handleCreateSession, handleDeleteSession, handleForkSession, handleGetSessionDetail, handleUpdateSession, } from "../server/handlers/sessions.js";
+import { handleCompactSession, handleCreateSession, handleDeleteSession, handleForkSession, handleGetSessionDetail, handleGetSessionMemoryStatus, handleUpdateSession, } from "../server/handlers/sessions.js";
 import { shutdownState } from "../server/shutdown.js";
 /**
  * Inline path matcher. Returns `null` for any path/method combination we
@@ -103,6 +103,17 @@ export function matchRoute(method, path) {
             return { route: "delete_session", id };
         return null;
     }
+    // /api/sessions/:id/memory and /api/sessions/:id/compact
+    const sessionActionMatch = /^\/api\/sessions\/([^/]+)\/(memory|compact)$/.exec(cleanPath);
+    if (sessionActionMatch) {
+        const id = decodeURIComponent(sessionActionMatch[1]);
+        const action = sessionActionMatch[2];
+        if (action === "memory" && method === "GET")
+            return { route: "get_session_memory", id };
+        if (action === "compact" && method === "POST")
+            return { route: "compact_session", id };
+        return null;
+    }
     // /api/sessions/:id/fork
     const forkMatch = /^\/api\/sessions\/([^/]+)\/fork$/.exec(cleanPath);
     if (forkMatch) {
@@ -128,7 +139,7 @@ export function matchRoute(method, path) {
  *         with the original Hono router which also 404'd)
  *  - 500: anything else; `error` field carries a sanitized message
  */
-export function handleRestRequest(frame, deps) {
+export async function handleRestRequest(frame, deps) {
     const { reqId, method, path, body } = frame;
     const logger = deps.logger ?? console;
     const match = matchRoute(method, path);
@@ -141,7 +152,7 @@ export function handleRestRequest(frame, deps) {
         };
     }
     try {
-        const result = dispatchRoute(match, body, deps);
+        const result = await dispatchRoute(match, body, deps);
         return {
             kind: "rest_response",
             reqId,
@@ -189,7 +200,7 @@ export function handleRestRequest(frame, deps) {
  * The body is `unknown` from the wire; each handler validates its own
  * shape via the `BadRequestError`-throwing checks they already do.
  */
-function dispatchRoute(match, body, deps) {
+async function dispatchRoute(match, body, deps) {
     const { store, manager, publishMetaEvent, logger } = deps;
     const id = match.id ?? "";
     switch (match.route) {
@@ -256,6 +267,8 @@ function dispatchRoute(match, body, deps) {
         }
         case "get_session":
             return handleGetSessionDetail(store, id);
+        case "get_session_memory":
+            return handleGetSessionMemoryStatus(store, manager, id);
         case "update_session": {
             const session = handleUpdateSession(store, id, asObject(body));
             safePublish(publishMetaEvent, logger, {
@@ -283,6 +296,8 @@ function dispatchRoute(match, body, deps) {
             }
             return { ok: true };
         }
+        case "compact_session":
+            return await handleCompactSession(store, manager, id);
         case "fork_session": {
             const session = handleForkSession(store, id, asObject(body));
             safePublish(publishMetaEvent, logger, {
@@ -450,11 +465,13 @@ export function handleClientMessage(frame, deps) {
     }
     const content = message.content;
     const isLoop = message.loop === true;
+    const loopMaxIterations = message.loopMaxIterations;
+    const loopGoal = message.loopGoal;
     const validImages = coerceImages(message.images);
     // Set autonomous iterative loop state before firing the prompt.
     // loop:true  → start/renew loop with the current content as original prompt;
     // loop:false → stop any active loop.
-    manager.setLoopActive(sessionId, isLoop, content);
+    manager.setLoopActive(sessionId, isLoop, content, loopMaxIterations, loopGoal);
     // 2. Attach (idempotent). On first attach we capture the replay payload
     //    and synthesize a `session_ready` ws_event so the browser sees the
     //    same first frame it would have on a direct WS connection.

package/dist/server/handlers/sessions.js

@@ -40,6 +40,25 @@ export function handleDeleteSession(store, id) {
     if (!deleted)
         throw new NotFoundError("Session not found");
 }
+export function handleGetSessionMemoryStatus(store, manager, id) {
+    const detail = store.getSession(id);
+    if (!detail)
+        throw new NotFoundError("Session not found");
+    return manager.getSessionMemoryStatus(id);
+}
+export async function handleCompactSession(store, manager, id) {
+    const detail = store.getSession(id);
+    if (!detail)
+        throw new NotFoundError("Session not found");
+    try {
+        await manager.compactSession(id);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new BadRequestError(message);
+    }
+    return { ok: true };
+}
 /**
  * Fork a session: create a new session copying all messages from the
  * source, with the `fork_compact_source_id` flag set so the

package/dist/server/pi-bridge.js

@@ -56,6 +56,8 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import aexolMcpExtension from "../extensions/aexol-mcp.js";
 import observationalMemory from "../memory/index.js";
+import { Runtime } from "../memory/runtime.js";
+import { OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, } from "../memory/types.js";
 import { fetchAllowedModels as defaultFetchAllowedModels, } from "../relay/models-fetch.js";
 /**
  * Synthetic provider names registered with pi's `ModelRegistry`. They route
@@ -294,8 +296,28 @@ function sanitizeRehydratedBlock(block) {
             `\n\n[truncated — ${omitted.toLocaleString()} bytes omitted]`,
     };
 }
+function normalizeSnapshotDetails(details) {
+    if (details.version === 4)
+        return details;
+    return {
+        type: "observational-memory",
+        version: 4,
+        observations: details.observations,
+        reflections: details.reflections,
+    };
+}
+function toRestoredMemorySnapshot(snapshot) {
+    return {
+        type: "observational-memory-snapshot",
+        version: 1,
+        coveredSourceCount: snapshot.coveredSourceCount,
+        summary: snapshot.summary,
+        details: normalizeSnapshotDetails(snapshot.details),
+    };
+}
 export class PiBridge {
     session;
+    sessionManager;
     unsubscribe;
     pending;
     disposed = false;
@@ -322,6 +344,8 @@ export class PiBridge {
     lastAppliedModelId;
     /** Current model's credit rates (from availableBaseModels), used for token_usage. */
     activeCreditRates = null;
+    memoryRuntime = new Runtime();
+    memoryPhase = "idle";
     constructor(opts) {
         this.opts = opts;
     }
@@ -369,6 +393,7 @@ export class PiBridge {
         await resourceLoader.reload();
         // In-memory session: SQLite is our source of truth.
         const sessionManager = SessionManager.inMemory(this.opts.cwd);
+        this.sessionManager = sessionManager;
         // Rehydrate session history so the LLM sees the full conversation
         // transcript from the beginning (not just the current prompt).
         // Tool calls and their results are reconstructed from the persisted
@@ -465,6 +490,22 @@ export class PiBridge {
             }
             console.info(`[PiBridge] Rehydrated ${this.opts.history.length} history message(s) into session context`);
         }
+        if (this.opts.memorySnapshot) {
+            const restoredSnapshot = toRestoredMemorySnapshot(this.opts.memorySnapshot);
+            sessionManager.appendCustomEntry(OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE, restoredSnapshot);
+            // Always inject the snapshot summary into LLM context. When raw
+            // history is also rehydrated, selectHistoryForBridge limits it to
+            // a small recent tail so duplication with the summary is minimal.
+            // The summary carries the compacted older context that would
+            // otherwise be lost after reconnect/restart.
+            if (restoredSnapshot.summary.trim().length > 0) {
+                sessionManager.appendCustomMessageEntry(OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE, restoredSnapshot.summary, false, {
+                    restoredFromSnapshot: true,
+                    coveredSourceCount: restoredSnapshot.coveredSourceCount,
+                });
+            }
+            console.info(`[PiBridge] Restored observational memory snapshot covering ${restoredSnapshot.coveredSourceCount} source entr${restoredSnapshot.coveredSourceCount === 1 ? "y" : "ies"}`);
+        }
         // Build a model registry that does NOT touch ~/.pi/agent/auth.json or
         // ~/.pi/agent/models.json — the backend is now the only source of
         // provider credentials and the only allowed inference target. We then
@@ -506,6 +547,9 @@ export class PiBridge {
         // Headless UI context: forwards extension notify() calls as wire events
         // so the browser can surface memory activity, MCP status, etc.
         const uiContext = createHeadlessUIContext((event) => {
+            if (event.type === "agent_notification") {
+                this.updateMemoryPhase(event.message, event.system);
+            }
             try {
                 this.opts.emit(event);
             }
@@ -666,6 +710,38 @@ export class PiBridge {
     getFirstAvailableModelId() {
         return this.allowedModels?.[0]?.modelId;
     }
+    getSessionBranch() {
+        return (this.sessionManager?.getBranch() ?? []);
+    }
+    getMemoryActivity() {
+        return {
+            phase: this.memoryPhase,
+            inFlight: {
+                observer: this.memoryRuntime.observerInFlight,
+                compaction: this.memoryRuntime.compactInFlight || this.memoryRuntime.compactHookInFlight,
+                reflection: this.memoryPhase === "reflecting",
+                pruner: this.memoryPhase === "pruning",
+            },
+        };
+    }
+    updateMemoryPhase(message, system) {
+        const lower = message.toLowerCase();
+        if (system === "memory_reflection" || lower.includes("reflector") || lower.includes("reflecting")) {
+            this.memoryPhase = "reflecting";
+            return;
+        }
+        if (system === "memory_pruner" || lower.includes("pruner") || lower.includes("pruning") || lower.includes("prune")) {
+            this.memoryPhase = "pruning";
+            return;
+        }
+        if (system === "memory_compaction" || lower.includes("compaction") || lower.includes("compact")) {
+            this.memoryPhase = "compacting";
+            return;
+        }
+        if (system === "memory_observer" || lower.includes("observer")) {
+            this.memoryPhase = "observing";
+        }
+    }
     async setModel(modelId) {
         if (!modelId)
             return true; // nothing to apply — pi keeps its current model
@@ -761,7 +837,18 @@ export class PiBridge {
     async compact(customInstructions) {
         if (!this.session)
             throw new Error("PiBridge.start() not called");
-        await this.session.compact(customInstructions);
+        this.memoryPhase = "compacting";
+        try {
+            await this.session.compact(customInstructions);
+        }
+        finally {
+            if (this.memoryPhase === "compacting" &&
+                !this.memoryRuntime.observerInFlight &&
+                !this.memoryRuntime.compactInFlight &&
+                !this.memoryRuntime.compactHookInFlight) {
+                this.memoryPhase = "idle";
+            }
+        }
     }
     dispose() {
         if (this.disposed)
@@ -795,6 +882,10 @@ export class PiBridge {
      * `events_jsonl` for the current assistant message.
      */
     emitAndBuffer(event) {
+        if (event.type === "compaction_start")
+            this.memoryPhase = "compacting";
+        if (event.type === "compaction_end")
+            this.memoryPhase = "idle";
         if (this.pending)
             this.pending.wireEvents.push(event);
         this.opts.emit(event);
@@ -1019,6 +1110,7 @@ export class PiBridge {
                     type: "compaction_end",
                     summary: ev.result?.summary ?? "",
                     tokensBefore: ev.result?.tokensBefore ?? 0,
+                    firstKeptEntryId: ev.result?.firstKeptEntryId,
                     aborted: ev.aborted,
                 });
                 return;

package/dist/server/session-stream.js

@@ -38,6 +38,11 @@
  */
 import { randomUUID } from "node:crypto";
 import { PiBridge } from "./pi-bridge.js";
+import { getMemoryState, isSourceEntry, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../memory/branch.js";
+import { observationPoolTokens, renderSummary } from "../memory/compaction.js";
+import { loadConfig } from "../memory/config.js";
+import { estimateStringTokens } from "../memory/tokens.js";
+import { reflectionContent } from "../memory/types.js";
 import { generateSessionTitle, isDefaultTitle, } from "./title-generator.js";
 const DEFAULT_BRIDGE_FACTORY = (args) => new PiBridge(args);
 /** Safety limit for autonomous loop iterations per session. */
@@ -47,6 +52,18 @@ const MAX_LOOP_ITERATIONS = 100;
  * Aligned with the observational memory extension default (memory/config.ts).
  */
 const LOOP_COMPACTION_THRESHOLD_TOKENS = 50_000;
+/**
+ * Defensive cap for fresh-bridge history replay when we already have a
+ * persisted observational-memory snapshot. Pi's own compaction keeps a
+ * recent live tail verbatim and summarizes the older prefix; replaying the
+ * entire SQLite transcript after restart defeats that and can explode the
+ * next prompt. We therefore rehydrate only an approximate recent tail.
+ *
+ * Keep this conservative — the tail is rehydrated as raw user/assistant
+ * messages PLUS pi reconstructs tool-result messages from events_jsonl,
+ * so the actual context inflation is 3-8× the stored token estimate.
+ */
+const REHYDRATION_TAIL_TOKEN_BUDGET = 20_000;
 /**
  * Number of accumulated wire events before flushing the in-flight turn
  * to SQLite. Batch-persisting means a server crash mid-turn only loses
@@ -55,6 +72,160 @@ const LOOP_COMPACTION_THRESHOLD_TOKENS = 50_000;
 const BATCH_FLUSH_INTERVAL = 10;
 /** Marker the agent emits in its response to signal the task is complete. */
 const LOOP_DONE_MARKER = "<LOOP_DONE>";
+function persistObservationalMemorySnapshot(store, sessionId, bridge) {
+    if (!bridge.getSessionBranch)
+        return;
+    try {
+        const entries = bridge.getSessionBranch();
+        const memoryState = getMemoryState(entries);
+        const allObservations = [...memoryState.committedObs, ...memoryState.pendingObs];
+        const hasMemory = memoryState.reflections.length > 0 || allObservations.length > 0;
+        if (!hasMemory) {
+            store.deleteSessionMemorySnapshot(sessionId);
+            return;
+        }
+        const summary = renderSummary(memoryState.reflections, allObservations);
+        const details = {
+            type: "observational-memory",
+            version: 4,
+            observations: allObservations,
+            reflections: memoryState.reflections,
+        };
+        store.upsertSessionMemorySnapshot(sessionId, {
+            summary,
+            details,
+            coveredSourceCount: entries.filter((entry) => isSourceEntry(entry)).length,
+        });
+    }
+    catch (err) {
+        console.warn(`[spectral] warn: failed to persist observational memory snapshot for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function estimateStoredMessageReplayTokens(message) {
+    return (estimateStringTokens(message.content) +
+        estimateStringTokens(message.events) +
+        (message.images?.length ?? 0) * 2_000);
+}
+function selectHistoryForBridge(history, hasMemorySnapshot) {
+    if (!history || history.length === 0)
+        return history;
+    if (!hasMemorySnapshot)
+        return history;
+    let total = 0;
+    let start = history.length - 1;
+    for (; start >= 0; start--) {
+        const nextTotal = total + estimateStoredMessageReplayTokens(history[start]);
+        if (total > 0 && nextTotal > REHYDRATION_TAIL_TOKEN_BUDGET)
+            break;
+        total = nextTotal;
+    }
+    const selected = history.slice(Math.max(0, start + 1));
+    return selected.length > 0 ? selected : [history[history.length - 1]];
+}
+function prunePersistedHistoryAfterCompaction(store, sessionId, bridge) {
+    if (!bridge.getSessionBranch)
+        return;
+    try {
+        const entries = bridge.getSessionBranch();
+        // Pi appends a CompactionEntry (type "compaction") at the end whose
+        // firstKeptEntryId marks the first branch entry that survives in LLM context.
+        // We scan backwards so we find the most recent compaction (there should be
+        // exactly one per compaction pass).
+        const lastCompaction = [...entries].reverse().find((entry) => entry.type === "compaction");
+        const firstKeptEntryId = lastCompaction?.firstKeptEntryId;
+        if (!firstKeptEntryId) {
+            console.log(`[spectral] prune: skipped – no compaction entry (or no firstKeptEntryId) ` +
+                `in branch for ${sessionId} (${entries.length} entries)`);
+            return;
+        }
+        const keptEntryIndex = entries.findIndex((entry) => entry.id === firstKeptEntryId);
+        if (keptEntryIndex === -1) {
+            console.log(`[spectral] prune: skipped – firstKeptEntryId "${firstKeptEntryId}" ` +
+                `not found in ${entries.length} branch entries for ${sessionId}`);
+            return;
+        }
+        // Count user + assistant messages in the kept portion of the branch.
+        // Tool-result entries are separate branch entries but are NOT separate
+        // SQLite rows – they live inside the assistant message's events_jsonl.
+        // Counting them would inflate the count and make the prune a silent no-op.
+        let keptPersistedMessageCount = 0;
+        for (let i = keptEntryIndex; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.type !== "message")
+                continue;
+            const role = entry.message && typeof entry.message === "object" && "role" in entry.message
+                ? entry.message.role
+                : undefined;
+            if (role === "user" || role === "assistant" || role === "system") {
+                keptPersistedMessageCount += 1;
+            }
+        }
+        const existing = store.getMessages(sessionId);
+        if (existing.length === 0)
+            return;
+        console.log(`[spectral] prune: ${sessionId} – branch has ${entries.length} entries, ` +
+            `kept portion starts at index ${keptEntryIndex} (id=${firstKeptEntryId}), ` +
+            `${keptPersistedMessageCount} user+assistant entries kept, ` +
+            `${existing.length} SQLite messages`);
+        if (keptPersistedMessageCount <= 0) {
+            console.log(`[spectral] prune: skipped – no kept messages for ${sessionId}`);
+            return;
+        }
+        if (keptPersistedMessageCount >= existing.length) {
+            console.log(`[spectral] prune: skipped – kept message count (${keptPersistedMessageCount}) ` +
+                `>= SQLite message count (${existing.length}) for ${sessionId}`);
+            return;
+        }
+        const keptMessages = existing.slice(-keptPersistedMessageCount);
+        const pruned = existing.length - keptMessages.length;
+        store.deleteMessagesBySession(sessionId);
+        for (const msg of keptMessages) {
+            store.appendMessage(sessionId, {
+                id: msg.id,
+                role: msg.role,
+                content: msg.content,
+                eventsJsonl: msg.events,
+                createdAt: msg.createdAt,
+                images: msg.images,
+            });
+        }
+        console.log(`[spectral] prune: finished – dropped ${pruned} pre-compaction message(s) ` +
+            `for ${sessionId}, ${keptMessages.length} kept`);
+    }
+    catch (err) {
+        console.warn(`[spectral] warn: failed to prune persisted history after compaction for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function defaultMemoryStatus(cwd) {
+    const config = loadConfig(cwd);
+    return {
+        mode: config.passive ? "passive" : "active",
+        phase: "idle",
+        inFlight: {
+            observer: false,
+            compaction: false,
+            reflection: false,
+            pruner: false,
+        },
+        reflections: { count: 0, tokens: 0 },
+        observations: {
+            committedCount: 0,
+            committedTokens: 0,
+            pendingCount: 0,
+            pendingTokens: 0,
+        },
+        thresholds: {
+            observation: config.observationThresholdTokens,
+            compaction: config.compactionThresholdTokens,
+            reflection: config.reflectionThresholdTokens,
+        },
+        progress: {
+            sinceObservationBoundTokens: 0,
+            sinceLastCompactionTokens: 0,
+            observationPoolTokens: 0,
+        },
+    };
+}
 export class SessionStreamManager {
     store;
     cwd;
@@ -145,6 +316,97 @@ export class SessionStreamManager {
         }
         return ids;
     }
+    getSessionMemoryStatus(sessionId) {
+        const detail = this.store.getSession(sessionId);
+        if (!detail)
+            throw new Error(`Unknown sessionId: ${sessionId}`);
+        const stream = this.streams.get(sessionId);
+        const config = loadConfig(stream?.cwd ?? this.cwd);
+        const status = defaultMemoryStatus(stream?.cwd ?? this.cwd);
+        status.mode = config.passive ? "passive" : "active";
+        const entries = stream?.bridge.getSessionBranch?.();
+        if (entries) {
+            const memoryState = getMemoryState(entries);
+            status.reflections = {
+                count: memoryState.reflections.length,
+                tokens: memoryState.reflections.reduce((sum, reflection) => sum + estimateStringTokens(reflectionContent(reflection)), 0),
+            };
+            status.observations = {
+                committedCount: memoryState.committedObs.length,
+                committedTokens: observationPoolTokens(memoryState.committedObs),
+                pendingCount: memoryState.pendingObs.length,
+                pendingTokens: observationPoolTokens(memoryState.pendingObs),
+            };
+            status.progress = {
+                sinceObservationBoundTokens: rawTokensSinceLastBound(entries),
+                sinceLastCompactionTokens: rawTokensSinceLastCompaction(entries),
+                observationPoolTokens: observationPoolTokens([
+                    ...memoryState.committedObs,
+                    ...memoryState.pendingObs,
+                ]),
+            };
+        }
+        else {
+            const snapshot = this.store.getSessionMemorySnapshot(sessionId);
+            if (snapshot) {
+                status.reflections = {
+                    count: snapshot.details.reflections.length,
+                    tokens: snapshot.details.reflections.reduce((sum, reflection) => sum + estimateStringTokens(reflectionContent(reflection)), 0),
+                };
+                status.observations = {
+                    committedCount: snapshot.details.observations.length,
+                    committedTokens: observationPoolTokens(snapshot.details.observations),
+                    pendingCount: 0,
+                    pendingTokens: 0,
+                };
+                status.progress.observationPoolTokens = observationPoolTokens(snapshot.details.observations);
+            }
+        }
+        const activity = stream?.bridge.getMemoryActivity?.();
+        if (activity) {
+            status.phase = activity.phase;
+            status.inFlight = activity.inFlight;
+        }
+        else if (stream?.compacting) {
+            status.phase = "compacting";
+            status.inFlight.compaction = true;
+        }
+        return status;
+    }
+    async compactSession(sessionId) {
+        if (this.disposed)
+            throw new Error("SessionStreamManager disposed");
+        const detail = this.store.getSession(sessionId);
+        if (!detail)
+            throw new Error(`Unknown sessionId: ${sessionId}`);
+        let stream = this.streams.get(sessionId);
+        if (!stream) {
+            stream = this.createStream(sessionId, detail.messages);
+            this.streams.set(sessionId, stream);
+        }
+        if (stream.currentTurn) {
+            throw new Error("Session is busy with an active turn");
+        }
+        if (stream.compacting) {
+            throw new Error("Session is already being compacted");
+        }
+        if (!stream.bridge.compact) {
+            throw new Error("Manual compaction is not supported for this session");
+        }
+        await stream.ready;
+        stream.compacting = true;
+        try {
+            await stream.bridge.compact();
+            // Prune persisted history synchronously after compaction, so even if the
+            // compaction_end event handler races or misses, SQLite reflects the
+            // compacted state before the next user prompt or reconnect.
+            prunePersistedHistoryAfterCompaction(this.store, sessionId, stream.bridge);
+        }
+        finally {
+            if (stream.compacting)
+                stream.compacting = false;
+        }
+    }
     /**
      * Persist a user message and forward it to pi. Resolves after the user
      * message is persisted + pi is invoked (NOT after the turn completes —
@@ -193,12 +455,15 @@ export class SessionStreamManager {
         // subscribers, cwd, and other metadata are preserved.
         if (stream.startError) {
             const history = this.store.getSession(sessionId)?.messages;
+            const memorySnapshot = this.store.getSessionMemorySnapshot(sessionId);
+            const bridgeHistory = selectHistoryForBridge(history, memorySnapshot != null);
             const bridgeOpts = {
                 cwd: stream.cwd,
                 agentDir: this.agentDir,
                 backendUrl: this.backendUrl,
                 machineJwt: this.machineJwt,
-                history,
+                history: bridgeHistory,
+                memorySnapshot,
                 emit: (event) => this.handleBridgeEvent(stream, event),
                 onAssistantMessageComplete: ({ messageId, content, eventsJsonl }) => {
                     try {
@@ -377,6 +642,7 @@ export class SessionStreamManager {
         // the next agent_end would otherwise trigger another prompt.
         stream.loopActive = false;
         stream.loopOriginalPrompt = null;
+        stream.loopGoal = null;
         stream.loopIterationCount = 0;
         // Dispose the pi bridge immediately — this tears down pi's session and
         // unsubscribe. The bridge's own event handler is detached; no further
@@ -466,13 +732,22 @@ export class SessionStreamManager {
      * The loop stops when the agent emits `<LOOP_DONE>` in its response or the
      * safety iteration limit is reached.
      */
-    setLoopActive(sessionId, active, originalPrompt) {
+    setLoopActive(sessionId, active, originalPrompt, maxIterations, goal) {
         const stream = this.streams.get(sessionId);
         if (stream) {
             stream.loopActive = active;
             stream.loopOriginalPrompt = active ? (originalPrompt ?? null) : null;
-            if (!active)
+            if (active) {
+                if (maxIterations !== undefined && maxIterations > 0) {
+                    stream.loopMaxIterations = Math.min(maxIterations, MAX_LOOP_ITERATIONS);
+                }
+                stream.loopGoal = goal?.trim() || null;
+            }
+            else {
                 stream.loopIterationCount = 0;
+                stream.loopMaxIterations = MAX_LOOP_ITERATIONS;
+                stream.loopGoal = null;
+            }
         }
     }
     /**
@@ -560,6 +835,20 @@ export class SessionStreamManager {
      * entry → prepareCompaction() returns undefined → "Already compacted"
      * → the trigger's onError handler catches it harmlessly.
      */
+    buildLoopPrompt(stream) {
+        const parts = [];
+        if (stream.loopGoal) {
+            parts.push(`[GOAL]: ${stream.loopGoal}`);
+            parts.push("");
+        }
+        parts.push(stream.loopOriginalPrompt);
+        if (stream.loopGoal) {
+            parts.push("");
+            parts.push("After completing your work, evaluate whether the goal has been FULLY achieved. " +
+                'Include <LOOP_DONE> in your response ONLY if you are confident the goal is completely met.');
+        }
+        return parts.join("\n");
+    }
     async sendNextLoopIteration(stream) {
         const shouldCompact = stream.bridge.compact &&
             typeof stream.contextWindowUsed === "number" &&
@@ -581,7 +870,7 @@ export class SessionStreamManager {
                 }
             }
         }
-        await this.prompt(stream.sessionId, stream.loopOriginalPrompt, undefined);
+        await this.prompt(stream.sessionId, this.buildLoopPrompt(stream), undefined);
     }
     // --- internals ----------------------------------------------------------
     createStream(sessionId, history) {
@@ -612,17 +901,22 @@ export class SessionStreamManager {
             loopActive: false,
             loopIterationCount: 0,
             loopOriginalPrompt: null,
+            loopMaxIterations: MAX_LOOP_ITERATIONS,
+            loopGoal: null,
             forkCompactSourceId: forkSourceId ?? null,
             compacting: false,
             contextWindowUsed: null,
             contextWindowMax: null,
         };
+        const memorySnapshot = this.store.getSessionMemorySnapshot(sessionId);
+        const bridgeHistory = selectHistoryForBridge(history, memorySnapshot != null);
         const bridgeOpts = {
             cwd,
             agentDir: this.agentDir,
             backendUrl: this.backendUrl,
             machineJwt: this.machineJwt,
-            history,
+            history: bridgeHistory,
+            memorySnapshot,
             emit: (event) => this.handleBridgeEvent(stream, event),
             onAssistantMessageComplete: ({ messageId, content, eventsJsonl }) => {
                 try {
@@ -769,9 +1063,14 @@ export class SessionStreamManager {
         }
         if (event.type === "compaction_end") {
             stream.compacting = false;
+            if (!event.aborted) {
+                prunePersistedHistoryAfterCompaction(this.store, stream.sessionId, stream.bridge);
+            }
+            persistObservationalMemorySnapshot(this.store, stream.sessionId, stream.bridge);
         }
         this.broadcast(stream, event);
         if (event.type === "agent_end") {
+            persistObservationalMemorySnapshot(this.store, stream.sessionId, stream.bridge);
             // Final flush + clear batch-persist tracking. `onAssistantMessageComplete`
             // has already written the authoritative final row to SQLite (it fires on
             // `message_end`, which precedes `agent_end`), so the staged row is already
@@ -797,15 +1096,17 @@ export class SessionStreamManager {
                     stream.loopActive = false;
                     stream.loopIterationCount = 0;
                     stream.loopOriginalPrompt = null;
+                    stream.loopGoal = null;
                     this.broadcast(stream, {
                         type: "loop_complete",
                         iterations: completedIterations,
                     });
                 }
-                else if (stream.loopIterationCount >= MAX_LOOP_ITERATIONS) {
-                    console.log(`[loop] max iterations (${MAX_LOOP_ITERATIONS}) reached, stopping`);
+                else if (stream.loopIterationCount >= stream.loopMaxIterations) {
+                    console.log(`[loop] max iterations (${stream.loopMaxIterations}) reached, stopping`);
                     stream.loopActive = false;
                     stream.loopOriginalPrompt = null;
+                    stream.loopGoal = null;
                     this.broadcast(stream, {
                         type: "loop_max_iterations",
                         iterations: stream.loopIterationCount,
@@ -813,17 +1114,18 @@ export class SessionStreamManager {
                 }
                 else {
                     stream.loopIterationCount++;
-                    console.log(`[loop] iteration ${stream.loopIterationCount}/${MAX_LOOP_ITERATIONS}`);
+                    console.log(`[loop] iteration ${stream.loopIterationCount}/${stream.loopMaxIterations}`);
                     this.broadcast(stream, {
                         type: "loop_iteration",
                         iteration: stream.loopIterationCount,
-                        maxIterations: MAX_LOOP_ITERATIONS,
+                        maxIterations: stream.loopMaxIterations,
                         prompt: stream.loopOriginalPrompt,
                     });
                     void this.sendNextLoopIteration(stream).catch((err) => {
                         console.error(`[loop] iteration failed: ${err instanceof Error ? err.message : String(err)}`);
                         stream.loopActive = false;
                         stream.loopOriginalPrompt = null;
+                        stream.loopGoal = null;
                     });
                 }
             }

package/dist/server/storage.js

@@ -36,7 +36,7 @@ import { stripJsoncComments } from "../studio-binding.js";
  * Since this is local-only conversation history pre-1.0, we explicitly do not
  * preserve user data across schema changes.
  */
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
 const SCHEMA_SQL = `
 PRAGMA foreign_keys = ON;
 
@@ -70,6 +70,14 @@ CREATE TABLE IF NOT EXISTS messages (
 );
 
 CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at);
+
+CREATE TABLE IF NOT EXISTS session_memory_snapshots (
+  session_id TEXT PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
+  summary TEXT NOT NULL,
+  details_json TEXT NOT NULL,
+  covered_source_count INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
 `;
 /**
  * Synchronous binding-file reader for a project at the given filesystem path.
@@ -100,7 +108,7 @@ function applyBindingFields(project) {
     };
 }
 /** Tables we own — used by the migration drop step. */
-const KNOWN_TABLES = ["messages", "sessions", "projects"];
+const KNOWN_TABLES = ["session_memory_snapshots", "messages", "sessions", "projects"];
 /** Best-effort parse of the `images_json` column into `ImageAttachment[]`. */
 function parseImagesJson(raw) {
     if (!raw || raw === "")
@@ -148,9 +156,13 @@ export class SessionStore {
     stmtListMessages;
     stmtAppendMessage;
     stmtDeleteMessage;
+    stmtDeleteMessagesBySession;
     stmtTouchSession;
     stmtRenameSession;
     stmtSessionWithCount;
+    stmtGetSessionMemorySnapshot;
+    stmtUpsertSessionMemorySnapshot;
+    stmtDeleteSessionMemorySnapshot;
     // Phase 3: per-session sticky model.
     stmtGetSessionModel;
     stmtSetSessionModel;
@@ -276,6 +288,7 @@ export class SessionStore {
         this.stmtAppendMessage = this.db.prepare(`INSERT OR REPLACE INTO messages (id, session_id, role, content, events_jsonl, images_json, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)`);
         this.stmtDeleteMessage = this.db.prepare(`DELETE FROM messages WHERE id = ?`);
+        this.stmtDeleteMessagesBySession = this.db.prepare(`DELETE FROM messages WHERE session_id = ?`);
         this.stmtTouchSession = this.db.prepare(`UPDATE sessions SET updated_at = ? WHERE id = ?`);
         this.stmtRenameSession = this.db.prepare(`UPDATE sessions SET title = ?, updated_at = ? WHERE id = ?`);
         this.stmtSessionWithCount = this.db.prepare(`
@@ -284,6 +297,12 @@ export class SessionStore {
       FROM sessions s
       WHERE s.id = ?
     `);
+        this.stmtGetSessionMemorySnapshot = this.db.prepare(`SELECT session_id, summary, details_json, covered_source_count, updated_at
+       FROM session_memory_snapshots WHERE session_id = ?`);
+        this.stmtUpsertSessionMemorySnapshot = this.db.prepare(`INSERT OR REPLACE INTO session_memory_snapshots
+       (session_id, summary, details_json, covered_source_count, updated_at)
+       VALUES (?, ?, ?, ?, ?)`);
+        this.stmtDeleteSessionMemorySnapshot = this.db.prepare(`DELETE FROM session_memory_snapshots WHERE session_id = ?`);
         this.stmtGetSessionModel = this.db.prepare(`SELECT model_id FROM sessions WHERE id = ?`);
         this.stmtSetSessionModel = this.db.prepare(`UPDATE sessions SET model_id = ? WHERE id = ?`);
         this.stmtSetForkCompactSource = this.db.prepare(`UPDATE sessions SET fork_compact_source_id = ? WHERE id = ?`);
@@ -463,6 +482,15 @@ export class SessionStore {
             console.error(`[spectral] error: deleteMessage failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /** Delete all persisted messages for a session. */
+    deleteMessagesBySession(sessionId) {
+        try {
+            this.stmtDeleteMessagesBySession.run(sessionId);
+        }
+        catch (err) {
+            console.error(`[spectral] error: deleteMessagesBySession failed for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     appendMessage(sessionId, msg) {
         const id = msg.id ?? randomUUID();
         const createdAt = msg.createdAt ?? Date.now();
@@ -511,6 +539,34 @@ export class SessionStore {
         return info.changes > 0;
     }
     // ----------------------------------------------------------------------
+    // Observational memory snapshot persistence
+    // ----------------------------------------------------------------------
+    getSessionMemorySnapshot(sessionId) {
+        const row = this.stmtGetSessionMemorySnapshot.get(sessionId);
+        if (!row)
+            return null;
+        try {
+            return {
+                sessionId: row.session_id,
+                summary: row.summary,
+                details: JSON.parse(row.details_json),
+                coveredSourceCount: row.covered_source_count,
+                updatedAt: row.updated_at,
+            };
+        }
+        catch (err) {
+            console.warn(`[storage] invalid memory snapshot for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    upsertSessionMemorySnapshot(sessionId, snapshot) {
+        const now = Date.now();
+        this.stmtUpsertSessionMemorySnapshot.run(sessionId, snapshot.summary, JSON.stringify(snapshot.details), snapshot.coveredSourceCount, now);
+    }
+    deleteSessionMemorySnapshot(sessionId) {
+        this.stmtDeleteSessionMemorySnapshot.run(sessionId);
+    }
+    // ----------------------------------------------------------------------
     // Per-session sticky model (Phase 3 — Available Models whitelist)
     // ----------------------------------------------------------------------
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.4.12",
+  "version": "0.6.0",
   "description": "Always-on coding agent for Aexol — branded pi wrapper with relay-based browser access.",
   "type": "module",
   "private": false,