@vortex-os/memory-extended 0.5.1

package/README.md

@@ -0,0 +1,244 @@
+# @vortex-os/memory-extended
+
+Extended memory layer for VortEX — an **opt-in add-on** that lives on top of `@vortex-os/base`. Adds derived indexes and a conversation archive while keeping the base's markdown `_memory/` layer as the single source of truth.
+
+## What it is
+
+`memory-extended` ships as a **single npm package** with six cooperating **namespaces**:
+
+| Namespace | Purpose | Status |
+|---|---|---|
+| `sessionArchive` | Append-only JSONL log of agent sessions + SQLite metadata. Four first-party host adapters (Claude Code CLI, Codex CLI, Gemini CLI, Claude Desktop). | Phase 11b — **shipped (0.1.0)** |
+| `consolidate` | Post-session fact-extraction proposer — read past `sessionArchive` events, propose memory candidates, operator confirms. | Phase 11d — **shipped (0.1.0)** |
+| `sqlite` | Structured store derived from markdown memories — hard-filter queries (`byType` / `byTag` / `byPrivacy` / `updatedSince`), drift detection (log + skip, non-destructive). | Phase 11a — **shipped (0.2.0)**. Five operator decisions recorded in `docs/memory-extended-design.md`. |
+| `vector` | Dense retrieval over memories **and conversation sessions**. Default backend: **in-process brute-force cosine**; vectors in the shared `memory.sqlite`. Host-injected `EmbedFn` (multilingual local default). Sessions are vectorized at topic-chunk granularity via embedding-similarity segmentation. | Phase 11c — **shipped (0.3.0+)** |
+| `recall` | Two-stage hybrid retrieval **engine** (SQLite loose hard-filter → cosine rerank). Returns data, not a report. Hits carry `source` = `memory` \| `session-archive`. `/recall <query>` command lives in `session-rituals`. | Phase 11c — **shipped (0.3.0+)** |
+| `mcp` | MCP server for any MCP host (Claude Desktop, chatbots) over stdio: read tools (`recall`, `list_memories`, `get_memory`) + document tools (`suggest_document` → `write_document` / `decline_document`, a propose-then-write pair), plus a one-line `install` into the host config. Writes are gated behind an explicit second tool call. SDK is an optional dependency. Bin: `vortex-mcp-recall`. | **shipped (0.5.0+)** |
+
+The companion module **`proactive-curator`** (shipped inside `@vortex-os/base`) handles the *in-session* counterpart to `consolidate` — live "this looks worth capturing" prompts during an ongoing conversation. `memory-extended/consolidate` reuses its `Proposal` / `LLMJudge` types via the base aggregate, so a single host UX renders both surfaces.
+
+## What it is not
+
+- It does **not** replace `@vortex-os/base`'s `memorySystem`. The markdown layer remains the source of truth; this package adds *derived* indexes that can be deleted and regenerated at any time.
+- It does **not** write to `_memory/` directly. The `consolidate` namespace proposes; the operator confirms; writes go through `base`'s `memorySystem`.
+- It does **not** require all five namespaces to be present. Use what you need; drop the rest.
+
+## Installation
+
+```sh
+npm install @vortex-os/memory-extended @vortex-os/base better-sqlite3
+# Optional — only needed if you ingest from Claude Desktop:
+npm install classic-level
+```
+
+`@vortex-os/base` is a required peer dependency — `consolidate` reuses the `proactiveCurator` namespace it exposes for `Proposal` / `LLMJudge` types. `better-sqlite3` is required for the SQLite metadata layer. `classic-level` is optional — required only when the Claude Desktop adapter is registered.
+
+The local embedder (`@huggingface/transformers`) is an **optional dependency** — it installs automatically with this package; nothing to fetch by hand. The default model is **`Xenova/multilingual-e5-small`** (384-dim, 50+ languages incl. Korean, 512-token input, ~470 MB) — a retrieval-tuned multilingual model that downloads once on first `vector`/`recall` use and is cached. It is *asymmetric*: a `"query: "` prefix is applied to search text and `"passage: "` to indexed text automatically (the store passes the right `kind`). To use a *symmetric* model instead (e.g. `Xenova/all-MiniLM-L6-v2`, ~90 MB) pass `{ model: "...", prefixes: null }`. To skip the local model entirely, pass your own `EmbedFn` (e.g. an OpenAI/Voyage adapter).
+
+> **Changing the embedder requires a vector rebuild.** Vectors are model-specific; even when the dimension matches (384-dim) the embedding *spaces* differ, so run `npx rebuild-memory-vector` after switching models.
+
+## Quick usage — `sessionArchive`
+
+```ts
+import {
+  ingest,
+  claudeCodeAdapter,
+  codexAdapter,
+  geminiAdapter,
+  claudeDesktopAdapter,
+} from "@vortex-os/memory-extended/sessionArchive";
+
+await ingest({
+  adapters: [claudeCodeAdapter, codexAdapter, geminiAdapter, claudeDesktopAdapter],
+  cwd: process.cwd(),
+  dataDir: "./data",
+  since: "2026-05-01T00:00:00Z",
+});
+```
+
+The orchestrator runs each adapter's `detect()` in parallel, calls `list()` on the ones that resolve true, reads each session end-to-end, normalizes events to `VortexTranscriptEvent`, and writes raw + normalized JSONL into `data/_session-archive/` along with SQLite metadata for incremental re-scan.
+
+## Quick usage — `sqlite`
+
+```ts
+import { MemorySqliteStore, rebuildFromMemoryDir, driftCheck } from "@vortex-os/memory-extended/sqlite";
+
+const store = new MemorySqliteStore("./data/_indexes/memory.sqlite");
+
+// One-shot rebuild from data/_memory/*.md (or run `npx rebuild-memory-sqlite`).
+await rebuildFromMemoryDir(store, "./data/_memory");
+
+// Four hard-filter helpers.
+const rules = store.byType("feedback");
+const koreanRules = store.byTag("korean");
+const visiblePublic = store.byPrivacy("public");
+const fresh = store.updatedSince("2026-05-01");
+
+// Composite query (AND across fields, OR within a list).
+const recent = store.query({
+  type: ["feedback", "project"],
+  tags: ["vortex"],
+  updatedSinceMs: Date.parse("2026-05-20"),
+});
+
+// Drift check — non-destructive. Returns the drifted ids; the operator
+// decides whether to re-run rebuild or treat the markdown as new truth.
+const report = await driftCheck(store, "./data/_memory");
+console.log(`drifted ${report.drifted.length}/${report.rowsScanned}`);
+
+store.close();
+```
+
+The sqlite file lives under `data/_indexes/` (gitignored). Markdown remains the source of truth — the sqlite index is derived and rebuildable. See the operator decision table in [`docs/memory-extended-design.md`](../../docs/memory-extended-design.md#sqlite-namespace) for the rationale.
+
+## Quick usage — `vector` + `recall`
+
+```ts
+import { MemorySqliteStore } from "@vortex-os/memory-extended/sqlite";
+import { MemoryVectorStore, createLocalEmbedder } from "@vortex-os/memory-extended/vector";
+import { recall, renderRecallHits } from "@vortex-os/memory-extended/recall";
+
+const dbPath = "./data/_indexes/memory.sqlite";
+const sqlite = new MemorySqliteStore(dbPath);
+const vector = new MemoryVectorStore({ db: dbPath }); // default brute-force cosine backend
+const embed = createLocalEmbedder();                  // or your own EmbedFn (OpenAI/Voyage)
+
+// One-shot rebuild from the sqlite store (or run `npx rebuild-memory-vector`).
+await vector.rebuild(sqlite, embed);                  // → { indexed, skipped, pruned }
+
+// The engine returns DATA — list it, or phrase one hit in conversation.
+const result = await recall(
+  { query: "tone feedback from 5월", k: 5 },          // intent: type/tag/Korean-month parsed loosely
+  { sqlite, vector, embed },
+);
+console.log(renderRecallHits(result));                // optional compact list render
+
+vector.close();
+sqlite.close();
+```
+
+The vector index shares the same `memory.sqlite` (a `memory_vectors` table) — one file, one rebuild path. The `/recall <query>` slash command wraps this engine; register it via `createRitualRegistry({ recall: { embed } })` in `@vortex-os/session-rituals`. The engine returns structured hits rather than a report so the host can either render a list or weave a hit into conversation (operator decision 5). See [`docs/memory-extended-design.md`](../../docs/memory-extended-design.md#vector-namespace) for the backend/embedder rationale.
+
+**Conversation sessions** are searchable too. `vector.rebuildSessions(sessionArchiveStore, embed)` vectorizes each archived session and stores chunks under `source: "session-archive"` plus a `session_chunks` metadata row for hydration. Run `npx rebuild-memory-vector --sessions`. `recall` then returns session hits alongside memory hits (pass a `SessionChunkStore` as `sessionChunks` to hydrate them; without it session hits are skipped). Filter to one corpus with `/recall <q> --source session-archive`.
+
+Granularity is `"turn"` by default — one chunk per user+assistant exchange — which a real-data tuning run found equals or beats topic segmentation while staying simple (`"segment"` mode is available for coarser topic chunks). The bigger quality lever is the **content filter**: only user/assistant text is indexed; tool output (git/ls/npm dumps) and host system-reminder blocks are stripped so the index reflects what was discussed. Recall precision on short conversational turns is bounded by the embedder — the `multilingual-e5-small` default reliably ranks the on-topic hit first (it fixed a discrimination failure the earlier MiniLM default had) at the same weight class; for sharper still, swap in a stronger `EmbedFn` (e.g. `bge-m3`, heavier — best hosted on a GPU and called remotely).
+
+## Quick usage — `mcp` (memory tools over stdio)
+
+The `mcp` namespace exposes six tools so any MCP-capable host (Claude Desktop,
+chatbots, other agents) can work with the user's memory:
+
+**Read tools** — `recall` (semantic search), `list_memories` (filtered
+summaries), `get_memory` (one entry in full).
+
+**Document tools** — a deliberate propose-then-write pair so the only write
+surface is gated behind an explicit second call (honoring "auto the plumbing,
+propose the prose" — operational records are auto-kept; formal documents are
+proposed, then written only on acceptance):
+- `suggest_document(topic, name, content, …)` — returns a preview + target path
+  + fingerprint, **writes nothing**. Flags if the target exists or was declined.
+- `write_document(…)` — the explicit second step; creates
+  `data/<topic>/<name>.md` with frontmatter (never overwrites) and records the
+  acceptance.
+- `decline_document(topic, name)` — suppresses the same suggestion for ~30 days.
+
+Because these are memory features, they ship **inside this package** rather than
+as a separate install. The MCP SDK (`@modelcontextprotocol/sdk`) is an
+**optional** dependency, loaded at runtime only when the server runs — consumers
+who never run it pay nothing for it.
+
+Run the bundled stdio server (usually launched by the host, not by hand):
+
+```sh
+npx vortex-mcp-recall --data-dir ./data
+```
+
+It self-resolves the data dir from `--data-dir`, then `VORTEX_DATA_DIR`, then the
+cwd, and reads the recall index at `<dataDir>/_indexes/memory.sqlite`. The
+embedder loads once at startup and is reused for every query.
+
+Claude Desktop (`claude_desktop_config.json`, one-time setup):
+
+```json
+{
+  "mcpServers": {
+    "vortex-recall": {
+      "command": "npx",
+      "args": ["vortex-mcp-recall", "--data-dir", "/absolute/path/to/instance/data"]
+    }
+  }
+}
+```
+
+Programmatic use (attach your own transport):
+
+```ts
+import { vector, mcp } from "@vortex-os/memory-extended";
+
+const server = await mcp.createRecallServer({
+  embed: vector.createLocalEmbedder(),
+  dbPath: "./data/_indexes/memory.sqlite",
+});
+// await server.connect(transport)
+```
+
+## Quick usage — `consolidate`
+
+```ts
+import { SessionArchiveStore } from "@vortex-os/memory-extended/sessionArchive";
+import { Consolidator } from "@vortex-os/memory-extended/consolidate";
+import { proactiveCurator } from "@vortex-os/base";
+
+const store = new SessionArchiveStore("./data");
+const consolidator = new Consolidator(store, process.cwd(), {
+  defaultLookbackDays: 7,
+});
+
+// Host-supplied LLM adapter — see @vortex-os/base "Opt-in /curate surface"
+// for the Claude Code wiring example.
+const llm = new proactiveCurator.ClaudeCodeLLMJudge(async ({ prompt }) => {
+  return await invokeMySubAgent(prompt);
+});
+
+const proposals = await consolidator.propose({}, { llm, now: new Date() });
+// Each proposal carries onAccept / onDecline thunks. Surface them to the
+// operator; on accept the memory file is written under data/_memory/<name>.md
+// via a single create-file action.
+```
+
+The consolidator queries recently-ingested sessions from `sessionArchive`, asks the LLM for memory candidates with explicit source-event citations, drops candidates whose fingerprint is on the rejected list (30-day expiry), and returns proposals shaped exactly like `proactive-curator` outputs — so a single `/curate`-style host UX renders both in-session capture and post-session consolidation.
+
+## Privacy & network behavior
+
+- **Embedding model download.** The `vector` / `recall` namespaces use the
+  `e5-small` sentence-embedding model via `@huggingface/transformers`. On first
+  use the model weights are fetched (HTTP `GET`, read-only) from `huggingface.co`
+  and cached locally. To run fully offline: set `HF_HUB_OFFLINE=1`, pre-seed the
+  Hugging Face cache directory, or pass your own `EmbedFn` to skip the bundled
+  model entirely. No data is uploaded — the download is one-directional.
+- **Consolidation and the host LLM.** The `consolidate` namespace sends excerpts
+  of your archived session transcripts to whatever LLM adapter the host wires in
+  (the `LLMJudge` you supply). Those excerpts leave the process only through that
+  adapter; choose one whose data-handling you trust.
+- **Local storage permissions.** Archived raw transcripts, the normalized JSONL,
+  and the SQLite indexes are written under `data/_session-archive/` with
+  owner-only permissions (`0o700` dirs / `0o600` files) on POSIX hosts. This is a
+  no-op on Windows.
+- **Verbatim transcript content + git tracking.** The normalized JSONL under
+  `data/_session-archive/normalized/` stores **verbatim** conversation content —
+  every user and assistant message as it was written. If you enable git tracking
+  for that path (the normalized layer is the cross-machine source of truth, so
+  this is a reasonable choice), any secret that appeared in a transcript — an API
+  token pasted into a prompt, a password in a tool result — is committed and
+  synced along with it. To scrub such patterns *before* the normalized files are
+  written, supply an ingest-time redaction hook via `AdapterOptions.redact`
+  (passed as `options.redact` to `ingest`): it runs on every event after
+  normalization and before storage, so a regex that masks token-shaped strings
+  keeps them out of the archive entirely.
+
+## Design documents
+
+- [`docs/memory-extended-design.md`](../../docs/memory-extended-design.md) — cluster overview, sub-phase breakdown, industry pattern alignment
+- [`docs/transcript-adapter-design.md`](../../docs/transcript-adapter-design.md) — `sessionArchive` adapter interface, per-host schema mapping, on-disk storage, SQLite schema, lock-handling UX
+- [`docs/proactive-curator-design.md`](../../docs/proactive-curator-design.md) — in-session counterpart (separate module)
+- [`docs/architecture.md`](../../docs/architecture.md#multi-layer-memory-architecture) — multi-layer memory architecture, source-of-truth policy

package/dist/consolidate/index.d.ts

@@ -0,0 +1,7 @@
+export type { ArchivedSession, CollectSessionsOptions, } from "./query.js";
+export { collectRecentSessions, renderSessionForPrompt } from "./query.js";
+export type { RejectedEntry } from "./store.js";
+export { loadRejectedFingerprints, recordAcceptance, recordRejection, resetRejected, } from "./store.js";
+export type { ConsolidateAcceptResult, ConsolidateProposal, ConsolidatorOptions, MemoryCandidate, SourceExcerptId, } from "./types.js";
+export { Consolidator } from "./proposer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/consolidate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/consolidate/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE3E,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/consolidate/index.js

@@ -0,0 +1,4 @@
+export { collectRecentSessions, renderSessionForPrompt } from "./query.js";
+export { loadRejectedFingerprints, recordAcceptance, recordRejection, resetRejected, } from "./store.js";
+export { Consolidator } from "./proposer.js";
+//# sourceMappingURL=index.js.map

package/dist/consolidate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/consolidate/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAG3E,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAUpB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/consolidate/proposer.d.ts

@@ -0,0 +1,43 @@
+import type { LLMJudge } from "../internal/proactive-curator-helpers.js";
+import type { SessionArchiveStore } from "../sessionArchive/index.js";
+import type { ConsolidateProposal, ConsolidatorOptions } from "./types.js";
+/**
+ * Post-session consolidator. Reads recently-ingested sessions from the
+ * archive, asks the LLM to extract memory candidates from them, and
+ * returns a list of proposals that the host can surface to the user.
+ *
+ * The proposer is pure — it does not write to `_memory/` during `propose()`.
+ * Each returned proposal carries an `onAccept` thunk that writes the
+ * memory file (and records the acceptance) and an `onDecline` thunk that
+ * records the rejection. This matches the proactive-curator lifecycle so
+ * a single host UX can render both surfaces.
+ *
+ * Construction order (sub-phase 11d in `docs/memory-extended-design.md`):
+ *   propose()
+ *     -> query.collectRecentSessions(sinceMs, limit)
+ *     -> renderSessionForPrompt
+ *     -> LLMJudge.ask(extract-candidates prompt)
+ *     -> validate candidates + compute fingerprint
+ *     -> drop ones already on the rejected list
+ *     -> return ConsolidateProposal[]
+ *
+ * Fingerprint shape is `hash(candidate.name + body excerpt + sorted source IDs)`
+ * so the same memory can re-surface if the LLM's body shifts but stays
+ * suppressed if it lands on the same content again.
+ */
+export declare class Consolidator {
+    private readonly store;
+    private readonly cwd;
+    private readonly defaultLookbackDays;
+    private readonly maxSessionsPerRun;
+    private readonly maxCandidatesPerRun;
+    private readonly rejectionExpiryDays?;
+    constructor(store: SessionArchiveStore, cwd: string, options?: ConsolidatorOptions);
+    propose(input: {
+        readonly sinceMs?: number;
+    }, ctx: {
+        readonly llm: LLMJudge;
+        readonly now: Date;
+    }): Promise<readonly ConsolidateProposal[]>;
+}
+//# sourceMappingURL=proposer.d.ts.map

package/dist/consolidate/proposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposer.d.ts","sourceRoot":"","sources":["../../src/consolidate/proposer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEV,QAAQ,EAET,MAAM,0CAA0C,CAAC;AAYlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAS;gBAG3B,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,mBAAmB;IAUzB,OAAO,CACX,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EACpC,GAAG,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAClD,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;CAoE3C"}

package/dist/consolidate/proposer.js

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSafeBasename } from "../internal/proactive-curator-helpers.js";
+import { collectRecentSessions, renderSessionForPrompt, } from "./query.js";
+import { loadRejectedFingerprints, recordAcceptance, recordRejection, } from "./store.js";
+/**
+ * Post-session consolidator. Reads recently-ingested sessions from the
+ * archive, asks the LLM to extract memory candidates from them, and
+ * returns a list of proposals that the host can surface to the user.
+ *
+ * The proposer is pure — it does not write to `_memory/` during `propose()`.
+ * Each returned proposal carries an `onAccept` thunk that writes the
+ * memory file (and records the acceptance) and an `onDecline` thunk that
+ * records the rejection. This matches the proactive-curator lifecycle so
+ * a single host UX can render both surfaces.
+ *
+ * Construction order (sub-phase 11d in `docs/memory-extended-design.md`):
+ *   propose()
+ *     -> query.collectRecentSessions(sinceMs, limit)
+ *     -> renderSessionForPrompt
+ *     -> LLMJudge.ask(extract-candidates prompt)
+ *     -> validate candidates + compute fingerprint
+ *     -> drop ones already on the rejected list
+ *     -> return ConsolidateProposal[]
+ *
+ * Fingerprint shape is `hash(candidate.name + body excerpt + sorted source IDs)`
+ * so the same memory can re-surface if the LLM's body shifts but stays
+ * suppressed if it lands on the same content again.
+ */
+export class Consolidator {
+    store;
+    cwd;
+    defaultLookbackDays;
+    maxSessionsPerRun;
+    maxCandidatesPerRun;
+    rejectionExpiryDays;
+    constructor(store, cwd, options) {
+        this.store = store;
+        this.cwd = cwd;
+        this.defaultLookbackDays = options?.defaultLookbackDays ?? 7;
+        this.maxSessionsPerRun = options?.maxSessionsPerRun ?? 20;
+        this.maxCandidatesPerRun = options?.maxCandidatesPerRun ?? 5;
+        if (options?.rejectionExpiryDays !== undefined) {
+            this.rejectionExpiryDays = options.rejectionExpiryDays;
+        }
+    }
+    async propose(input, ctx) {
+        const sinceMs = input.sinceMs ?? ctx.now.getTime() - this.defaultLookbackDays * 24 * 60 * 60 * 1000;
+        const sessions = collectRecentSessions(this.store, {
+            sinceMs,
+            limit: this.maxSessionsPerRun,
+        });
+        if (sessions.length === 0)
+            return [];
+        const transcript = sessions.map(renderSessionForPrompt).join("\n\n---\n\n");
+        const prompt = buildExtractPrompt(transcript, this.maxCandidatesPerRun);
+        const expected = {
+            shape: "json",
+            schema: {
+                candidates: "MemoryCandidate[]",
+            },
+        };
+        const raw = await ctx.llm.ask(prompt, expected);
+        const candidates = normalizeCandidates(raw, sessions);
+        if (candidates.length === 0)
+            return [];
+        const rejected = await loadRejectedFingerprints(this.cwd, ctx.now);
+        const proposals = [];
+        for (const c of candidates) {
+            const fingerprint = computeCandidateFingerprint(c);
+            if (rejected.has(fingerprint))
+                continue;
+            const filename = `${c.name}.md`;
+            const action = {
+                kind: "create-file",
+                folderPath: "_memory",
+                filename,
+                body: renderMemoryBody(c, ctx.now),
+            };
+            const cwd = this.cwd;
+            const rejectionExpiryDays = this.rejectionExpiryDays;
+            proposals.push({
+                kind: "consolidate-memory",
+                fingerprint,
+                action,
+                candidate: c,
+                preview: renderPreview(c),
+                rationale: `Extracted from ${c.sourceExcerptIds.length} session excerpt(s); ${describeType(c.type)}.`,
+                sourceRefs: c.sourceExcerptIds.map(formatSourceRef),
+                onAccept: async () => {
+                    const writtenPath = await applyAction(cwd, action);
+                    await recordAcceptance(cwd, {
+                        fingerprint,
+                        candidateName: c.name,
+                        writtenPath,
+                        now: ctx.now,
+                    });
+                    return {
+                        writtenPath,
+                        actionApplied: "create-file",
+                        nextActionHint: `Memory written to _memory/${filename}. Edit freely; the source archive entries were not modified.`,
+                    };
+                },
+                onDecline: async () => {
+                    await recordRejection(cwd, {
+                        fingerprint,
+                        candidateName: c.name,
+                        now: ctx.now,
+                        ...(rejectionExpiryDays !== undefined ? { expiryDays: rejectionExpiryDays } : {}),
+                    });
+                },
+            });
+        }
+        return proposals;
+    }
+}
+function buildExtractPrompt(transcript, maxCandidates) {
+    return [
+        `You are reviewing past agent sessions to extract memory candidates worth remembering across future sessions.`,
+        ``,
+        `Read the transcripts and identify up to ${maxCandidates} concrete memory candidates. Each candidate should be either:`,
+        `  - a rule the operator established ("when X, do Y"),`,
+        `  - a stable fact about the operator or their setup ("operator's home network uses X"),`,
+        `  - a decision with durable scope ("we chose A over B for reason R").`,
+        ``,
+        `Do NOT propose routine status updates, transient debugging context, or anything the operator would obviously not want pinned across sessions.`,
+        ``,
+        `Return JSON:`,
+        `  { "candidates": [ { "name": "<slug-safe-id>", "description": "<one line>", "type": "user|feedback|project|reference", "body": "<markdown body, no frontmatter>", "sourceExcerptIds": [ { "host": "claude-code", "sessionId": "...", "eventIdx": 12 }, ... ] }, ... ] }`,
+        ``,
+        `If nothing is worth promoting, return { "candidates": [] }.`,
+        ``,
+        `Sessions:`,
+        transcript,
+    ].join("\n");
+}
+function normalizeCandidates(raw, sessions) {
+    if (typeof raw !== "object" || raw === null)
+        return [];
+    const obj = raw;
+    if (!Array.isArray(obj.candidates))
+        return [];
+    const validHostSession = new Set(sessions.map((s) => `${s.metadata.host}:${s.metadata.sessionId}`));
+    const out = [];
+    for (const c of obj.candidates) {
+        if (typeof c !== "object" || c === null)
+            continue;
+        const rec = c;
+        const name = slugify(String(rec.name ?? "").trim());
+        const description = String(rec.description ?? "").trim();
+        const type = String(rec.type ?? "").trim().toLowerCase();
+        const body = String(rec.body ?? "").trim();
+        if (!name || !description || !type || !body)
+            continue;
+        const sourceExcerptIds = extractSourceIds(rec.sourceExcerptIds, validHostSession);
+        if (sourceExcerptIds.length === 0)
+            continue;
+        out.push({ name, description, type, body, sourceExcerptIds });
+    }
+    return out;
+}
+function extractSourceIds(raw, valid) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const r of raw) {
+        if (typeof r !== "object" || r === null)
+            continue;
+        const rec = r;
+        const host = typeof rec.host === "string" ? rec.host : "";
+        const sessionId = typeof rec.sessionId === "string" ? rec.sessionId : "";
+        const eventIdx = typeof rec.eventIdx === "number" ? rec.eventIdx : NaN;
+        if (!host || !sessionId || !Number.isInteger(eventIdx))
+            continue;
+        if (!valid.has(`${host}:${sessionId}`))
+            continue;
+        out.push({ host, sessionId, eventIdx });
+    }
+    return out;
+}
+function slugify(s) {
+    return s.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function computeCandidateFingerprint(c) {
+    const normalized = JSON.stringify({
+        name: c.name,
+        bodyHead: c.body.slice(0, 200),
+        sourceIds: [...c.sourceExcerptIds]
+            .map((s) => `${s.host}:${s.sessionId}:${s.eventIdx}`)
+            .sort(),
+    });
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+function renderMemoryBody(c, now) {
+    const ymd = formatYmd(now);
+    return `---
+name: ${c.name}
+description: ${c.description}
+type: ${c.type}
+created: ${ymd}
+updated: ${ymd}
+tags: [consolidate, proactive-curator]
+---
+
+${c.body}
+
+## Sources
+
+${c.sourceExcerptIds.map((s) => `- ${formatSourceRef(s)}`).join("\n")}
+`;
+}
+function renderPreview(c) {
+    return [
+        `name: ${c.name}`,
+        `type: ${c.type}`,
+        `description: ${c.description}`,
+        "",
+        c.body,
+        "",
+        `Sources: ${c.sourceExcerptIds.length} excerpt(s)`,
+    ].join("\n");
+}
+function describeType(type) {
+    switch (type) {
+        case "user":
+            return "operator profile fact";
+        case "feedback":
+            return "rule / preference";
+        case "project":
+            return "project decision";
+        case "reference":
+            return "stable reference";
+        default:
+            return `type "${type}"`;
+    }
+}
+function formatSourceRef(s) {
+    return `${s.host}/${s.sessionId}#${s.eventIdx}`;
+}
+function formatYmd(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+async function applyAction(cwd, action) {
+    // Structural containment: consolidate always targets the fixed `_memory`
+    // system dir (which the canonical path gate rejects by design, so it cannot
+    // govern this write), and the filename is a model-derived candidate slug.
+    // Pin the folder and enforce a safe basename so a hostile name (separators,
+    // traversal, or a Windows colon/ADS) cannot escape `_memory/`.
+    if (action.folderPath !== "_memory") {
+        throw new Error(`refusing to write consolidated memory outside _memory/: got "${action.folderPath}"`);
+    }
+    assertSafeBasename(action.filename);
+    const folder = join(cwd, "data", action.folderPath);
+    await mkdir(folder, { recursive: true });
+    const file = join(folder, action.filename);
+    // Exclusive create (`wx`): the candidate name is an LLM-derived slug, so it
+    // can collide with an existing memory file. Never clobber — surface a clear
+    // conflict so the host can rename instead of silently overwriting. `onAccept`
+    // has no conflict field in `ConsolidateAcceptResult`, so a thrown Error is the
+    // cleanest signal: the host already awaits the accept thunk and propagates it.
+    try {
+        await writeFile(file, action.body, { encoding: "utf8", flag: "wx" });
+    }
+    catch (e) {
+        if (e.code === "EEXIST") {
+            throw new Error(`refusing to overwrite existing memory: ${action.folderPath}/${action.filename}`);
+        }
+        throw e;
+    }
+    return file;
+}
+//# sourceMappingURL=proposer.js.map

package/dist/consolidate/proposer.js.map

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

package/dist/consolidate/query.d.ts

@@ -0,0 +1,32 @@
+import type { EventRow, SessionMetadataRow, SessionArchiveStore } from "../sessionArchive/index.js";
+/**
+ * One archived session's content as the consolidator sees it — metadata
+ * plus the full ordered event list. Kept separate from
+ * `SessionArchiveStore` so the consolidator can shape its own
+ * presentation (LLM prompts, fingerprint inputs) without coupling to the
+ * archive's row layout.
+ */
+export interface ArchivedSession {
+    readonly metadata: SessionMetadataRow;
+    readonly events: readonly EventRow[];
+}
+export interface CollectSessionsOptions {
+    /** Only sessions ingested strictly after this epoch-ms cutoff. */
+    readonly sinceMs?: number;
+    /** Cap the number of sessions returned. Newest-ingested first. */
+    readonly limit?: number;
+}
+/**
+ * Pull the recently-ingested sessions together with their event bodies.
+ * Sessions with zero text events are dropped — they cannot drive a memory
+ * proposal, and feeding them to the LLM only wastes tokens.
+ */
+export declare function collectRecentSessions(store: SessionArchiveStore, options?: CollectSessionsOptions): readonly ArchivedSession[];
+/**
+ * Render an archived session as a compact transcript for an LLM prompt.
+ * Empty / tool-call-only events are dropped (they rarely carry the kind
+ * of insight worth promoting to memory); the remaining events are joined
+ * with `[<role>]` prefixes for the LLM to follow turn boundaries.
+ */
+export declare function renderSessionForPrompt(session: ArchivedSession): string;
+//# sourceMappingURL=query.d.ts.map

package/dist/consolidate/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/consolidate/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,SAAS,eAAe,EAAE,CAa5B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAYvE"}