dsh-companion-memory-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1326007879-sys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-companion-memory-core (v0)
+
+Local, host-independent long-term memory core for DeepSeek Harness. Plain-text
+notes, a bounded index, auditable evidence. No runtime dependencies, no external
+services, no native modules.
+
+Design notes live in the project plan and are not shipped in the npm package.
+
+## Current status
+
+The v0 implementation covers the data contract, three-source store, bounded
+index, keyword recall, layered disclosure, five tools, host `llm/stream`
+review, and a read-only client entry. `lib/` is generated by `npm run build`
+and shipped in the package.
+
+Review borrows the host's `ctx.llm.stream()` through `LlmReviewer`; it stays
+disabled by default via `maintenanceMode: off`. The idle-review chain (§7-3) is
+covered end to end by a host-shaped stream test, so no model quota is spent in CI.
+The client entry (`exports["./client"]`) registers a read-only sidebar action
+through the host's slot service; note browsing stays on the tool surface. A
+custom pane is deferred: host remote namespaces are Typert-generated, so a
+third-party plugin cannot register a new RPC group at runtime.
+
+The host exposes no `learning` / `contentMode` / `toolVerified` admission
+metadata, so unverified `tool/result` output is deliberately never archived.
+User and assistant messages are the only long-term sources in v0.
+
+The npm package name is `dsh-companion-memory-core`, distinct from the GitHub
+repository name.
+
+## Layout
+
+```
+src/core/        host-independent: paths, schema, store, indexer, recall,
+                 disclosure, context, review, writer, llm-adapter, llm-reviewer
+src/host/dsh/    the only layer allowed to touch the harness
+src/client/      read-only sidebar entry (exports["./client"])
+lib/             build output, the only code shipped in the npm package
+```
+
+## Build and install
+
+```sh
+npm install --no-package-lock --legacy-peer-deps
+npm run build                 # emits lib/**/*.js + .d.ts
+npm test
+npm pack                      # sanity-check the tarball contents
+dsh plugin --profile test add .
+```
+
+Local verification should use a dedicated `test` profile, never the daily one.
+
+## Data location
+
+Default `~/.companion/`, overridable with `config.memoryRoot` or the
+`COMPANION_MEMORY_ROOT` environment variable. Everything is plain text and
+stays on the machine:
+
+```
+MEMORY.md          bounded index (200 lines / 25 KB)
+meta.json          schema version, writer epoch, review watermark
+notes/*.md         one fact per file, with evidence and sourceRefs
+cold/*.jsonl       append-only raw conversation lines
+journal/           reserved for v1
+persona.md         reserved for v1
+profile.md         reserved for v1
+state.json         reserved for v1
+archive/           soft-archived notes
+index/             rebuildable keyword index
+```
+
+Uninstalling the plugin never deletes this directory. `memory_forget` archives a
+note and removes its index entry; it does not touch the host's own chat history.
+
+## Privacy and capability boundaries
+
+- Memory is **unencrypted plain text**; any local process can read it. Never
+  store credential values, only pointers to where they live.
+- The core never reads credentials and never opens network connections.
+- Review requests borrow the host's model through `LlmAdapter`; the package ships
+  no API key and no fallback provider.
+- `maintenanceMode: off` must produce zero model calls.
+
+## Before publishing
+
+1. Confirm peer ranges against the actual dsh release in use (verified against
+   desktop `0.2.2-rc.1` / `cordis 4.1.0`).
+2. Run `npm run build`, verify `lib/` and `icon.png` are in the tarball, then
+   `npm publish`.
+3. Add the `dsh-plugin` topic after the repository is at least one day old, then
+   submit one catalog YAML entry
+   `data/plugins/1326007879-sys__companion-memory.yml`. Note the 24-hour npm
+   release-age window.
+4. Keep descriptions factual: stable memory, local notes, bounded index. Do not
+   claim consciousness, emotions, or model training.
+
+## Out of scope for v0
+
+Persona/state injection, moods, proactive messages, journaling, vectors, graph
+links, star map, cross-host adapters, encryption, hash-chain audit, standalone
+service, model training.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+This project does not vendor third-party source code. The following projects
+were studied for their data formats, operating rules, and parameter defaults;
+only concepts and field names are reused.
+
+| Project | License | What is referenced |
+|---|---|---|
+| `tinqiao-oss/engramory` | MIT | One fact per Markdown file, bounded `MEMORY.md` index, write-before-limit discipline, single-writer/many-readers rule |
+| `Soulmate793/dsh-memory` | MIT | Recall score weights, decay and consolidation parameter defaults |
+| `123zxs345/dsh-plugin-companion-memory` | MIT | Session event filtering rules, stable source identity, layered disclosure shape |
+| `painter-7/memory-starmap` | **no LICENSE** | Data contract shape only (`cold` / `dream` / `daybook`, `evidence`, `supersededBy`). No code copied. |
+
+## Publishing notes
+
+This file is included in the published package via `package.json.files`. The
+catalog icon is a bitmap (`icon.png`), not SVG.

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# Each profile loads its own plugin instance; data lives outside the profile directory.
+- insert:
+    - id: companion-memory
+      name: dsh-companion-memory-core
+      disabled: !!js "!ctx.get('profileContext')"
+      config:
+        memoryRoot: ""          # empty = ~/.companion
+        companionId: default
+        idleReviewSeconds: 15
+        reviewMaxDelaySeconds: 60
+        candidateBudget: 24
+        contextTokens: 800
+        minimumScore: 0.05
+        maxLines: 200
+        maxBytes: 25600
+        reviewProvider: ""      # empty = current session request-header route
+        reviewModel: ""
+        maintenanceMode: off

package/lib/README.md

@@ -0,0 +1,3 @@
+Build output lives here; `npm run build` emits `lib/**/*.js` and `.d.ts`
+from `src/`. Only `lib/` is shipped as executable code in the npm package.
+These files are generated: change `src/`, never hand-edit `lib/`.

package/lib/client/index.d.ts

@@ -0,0 +1,8 @@
+import { type ClientContext } from './panel.js';
+/** Client-side Cordis plugin entry, discovered via exports["./client"]. */
+declare const _default: {
+    name: string;
+    apply(ctx: ClientContext): void;
+};
+export default _default;
+export { mountPanel, PANEL_ID, TOOL_NAMES, type ClientContext } from './panel.js';

package/lib/client/index.js

@@ -0,0 +1,9 @@
+import { mountPanel } from './panel.js';
+/** Client-side Cordis plugin entry, discovered via exports["./client"]. */
+export default {
+    name: 'dsh-companion-memory-client',
+    apply(ctx) {
+        mountPanel(ctx);
+    },
+};
+export { mountPanel, PANEL_ID, TOOL_NAMES } from './panel.js';

package/lib/client/panel.d.ts

@@ -0,0 +1,21 @@
+export declare const PANEL_ID = "companion-memory";
+export declare const TOOL_NAMES: readonly ["memory_recall", "memory_read", "memory_save", "memory_forget", "memory_stats"];
+interface ClientSlots {
+    inject(name: string, factory: () => unknown): unknown;
+    register(spec: Record<string, unknown>): unknown;
+}
+export interface ClientContext {
+    slots?: ClientSlots;
+    get?(name: string): unknown;
+}
+/**
+ * Registers a read-only sidebar entry through the host's slot service.
+ *
+ * The host renders `sidebar.footer.action` itself, so no React runtime or
+ * network client is added to this package. Full note browsing stays on the
+ * tool surface (`memory_stats` / `memory_recall` / `memory_read`); a custom
+ * pane with its own component would require a host-side remote RPC group.
+ * Registration is best-effort: a missing slot service must never break boot.
+ */
+export declare function mountPanel(client: ClientContext): boolean;
+export {};

package/lib/client/panel.js

@@ -0,0 +1,36 @@
+export const PANEL_ID = 'companion-memory';
+export const TOOL_NAMES = [
+    'memory_recall',
+    'memory_read',
+    'memory_save',
+    'memory_forget',
+    'memory_stats',
+];
+/**
+ * Registers a read-only sidebar entry through the host's slot service.
+ *
+ * The host renders `sidebar.footer.action` itself, so no React runtime or
+ * network client is added to this package. Full note browsing stays on the
+ * tool surface (`memory_stats` / `memory_recall` / `memory_read`); a custom
+ * pane with its own component would require a host-side remote RPC group.
+ * Registration is best-effort: a missing slot service must never break boot.
+ */
+export function mountPanel(client) {
+    const slots = client.slots;
+    if (typeof slots?.inject !== 'function' || typeof slots.register !== 'function')
+        return false;
+    try {
+        slots.inject('sidebar.footer.action', () => slots.register({
+            name: 'sidebar.footer.action',
+            id: PANEL_ID,
+            inject: () => ({
+                readOnly: true,
+                toolNames: [...TOOL_NAMES],
+            }),
+        }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/core/context.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryStore } from './store.js';
+/**
+ * Renders the prompt snapshot from the bounded index only. `cold` lines never
+ * contribute, so the injected context stays constant as the log grows.
+ */
+export declare function buildIndexSnapshot(store: MemoryStore, budget: number): Promise<string>;

package/lib/core/context.js

@@ -0,0 +1,14 @@
+import { estimateTokens } from './disclosure.js';
+/**
+ * Renders the prompt snapshot from the bounded index only. `cold` lines never
+ * contribute, so the injected context stays constant as the log grows.
+ */
+export async function buildIndexSnapshot(store, budget) {
+    const kept = [];
+    for (const line of await store.readIndex()) {
+        if (estimateTokens([...kept, line]) > budget)
+            break;
+        kept.push(line);
+    }
+    return kept.join('\n');
+}

package/lib/core/disclosure.d.ts

@@ -0,0 +1,20 @@
+export interface SummaryItem {
+    memoryId: string;
+    revision: number;
+    summary: string;
+    availableLayers: ['refined', 'raw'];
+}
+export interface DisclosureCandidate {
+    memoryId: string;
+    revision: number;
+    summary: string;
+    detailsUnavailable?: boolean;
+}
+export declare function estimateTokens(value: unknown): number;
+/** Summaries are the only layer that enters the prompt; details are fetched on demand. */
+export declare function summaryItems(memories: readonly DisclosureCandidate[], tokenBudget: number, maxItems?: number): SummaryItem[];
+/** Raw pages never truncate a source in the middle. */
+export declare function rawPage<T>(sources: readonly T[], offset?: number, pageSize?: number): {
+    sources: T[];
+    nextOffset?: number;
+};

package/lib/core/disclosure.js

@@ -0,0 +1,38 @@
+export function estimateTokens(value) {
+    return Math.ceil(new TextEncoder().encode(JSON.stringify(value)).length / 3);
+}
+/** Summaries are the only layer that enters the prompt; details are fetched on demand. */
+export function summaryItems(memories, tokenBudget, maxItems = 24) {
+    if (!Number.isFinite(tokenBudget) || tokenBudget <= 0)
+        return [];
+    const result = [];
+    const seen = new Set();
+    const limit = Math.min(24, Math.max(0, Math.floor(maxItems)));
+    for (const memory of memories) {
+        if (result.length >= limit)
+            break;
+        if (!memory.summary.trim())
+            continue;
+        const key = `${memory.memoryId}:${memory.revision}`;
+        if (seen.has(key))
+            continue;
+        const item = {
+            memoryId: memory.memoryId,
+            revision: memory.revision,
+            summary: memory.summary,
+            availableLayers: ['refined', 'raw'],
+        };
+        if (estimateTokens([...result, item]) > tokenBudget)
+            continue;
+        result.push(item);
+        seen.add(key);
+    }
+    return result;
+}
+/** Raw pages never truncate a source in the middle. */
+export function rawPage(sources, offset = 0, pageSize = 4) {
+    const start = Math.max(0, Math.floor(offset));
+    const sourcesPage = sources.slice(start, start + pageSize);
+    const next = start + pageSize;
+    return next < sources.length ? { sources: [...sourcesPage], nextOffset: next } : { sources: [...sourcesPage] };
+}

package/lib/core/index.d.ts

@@ -0,0 +1,11 @@
+export { resolveStoreRoot, storePaths, type StorePaths } from './paths.js';
+export { SCHEMA_VERSION, MAX_INDEX_LINES, MAX_INDEX_BYTES, NOTE_TYPES, STORE_LAYOUT, createEmptyMeta, formatNote, parseNote, noteFromRecord, validateColdRecord, type NoteType, type NoteState, type MaintenanceMode, type ColdRecord, type NoteFrontmatter, type Meta, } from './schema.js';
+export { FileLockWriter, type Writer } from './writer.js';
+export { MemoryStore, type StoredNote } from './store.js';
+export { featuresOf, buildKeywordIndex, idf, relevance, type KeywordIndex } from './indexer.js';
+export { recall, RECALL_WEIGHTS, ZONE_WEIGHTS, type RecallItem, type RecallHit, type RecallOptions, } from './recall.js';
+export { estimateTokens, summaryItems, rawPage, type SummaryItem, type DisclosureCandidate } from './disclosure.js';
+export { operationId, ReviewTiming, NoopReviewer, type ReviewRequest, type ReviewResult, type ReviewNote, type Reviewer, } from './review.js';
+export { disabledLlm, isBudgetError, type LlmAdapter, type LlmRequest, type LlmResult, } from './llm-adapter.js';
+export { LlmReviewer, type LlmReviewerOptions } from './llm-reviewer.js';
+export { buildIndexSnapshot } from './context.js';

package/lib/core/index.js

@@ -0,0 +1,11 @@
+export { resolveStoreRoot, storePaths } from './paths.js';
+export { SCHEMA_VERSION, MAX_INDEX_LINES, MAX_INDEX_BYTES, NOTE_TYPES, STORE_LAYOUT, createEmptyMeta, formatNote, parseNote, noteFromRecord, validateColdRecord, } from './schema.js';
+export { FileLockWriter } from './writer.js';
+export { MemoryStore } from './store.js';
+export { featuresOf, buildKeywordIndex, idf, relevance } from './indexer.js';
+export { recall, RECALL_WEIGHTS, ZONE_WEIGHTS, } from './recall.js';
+export { estimateTokens, summaryItems, rawPage } from './disclosure.js';
+export { operationId, ReviewTiming, NoopReviewer, } from './review.js';
+export { disabledLlm, isBudgetError, } from './llm-adapter.js';
+export { LlmReviewer } from './llm-reviewer.js';
+export { buildIndexSnapshot } from './context.js';

package/lib/core/indexer.d.ts

@@ -0,0 +1,14 @@
+/** English words plus Chinese character bigrams; no external tokenizer. */
+export declare function featuresOf(text: string): string[];
+export interface KeywordIndex {
+    docCount: number;
+    df: Record<string, number>;
+    postings: Record<string, string[]>;
+}
+export declare function buildKeywordIndex(docs: Array<{
+    id: string;
+    text: string;
+}>): KeywordIndex;
+export declare function idf(term: string, index: KeywordIndex): number;
+/** IDF-weighted feature overlap, normalized so long notes cannot dominate. */
+export declare function relevance(query: string, text: string, index: KeywordIndex): number;

package/lib/core/indexer.js

@@ -0,0 +1,61 @@
+const STOP_WORDS = new Set([
+    '现在', '可以', '这个', '那个', '什么', '怎么', '自己', '已经', '没有', '还是',
+    '就是', '如果', '因为', '所以', '但是', '然后', '今天', '明天', '时候', '一下',
+    '一个', '东西', '问题', '看看', '觉得', '应该', '需要', '不是', '我们', '你们',
+    '他们', '这样', '那样', '知道', '开始', '完成', '确认', '处理', '用户', '消息',
+    '任务', '结果', '内容', '情况', '部分', '方式', '功能', '文件',
+]);
+const TOKEN_RE = /[A-Za-z][A-Za-z0-9_-]{2,}|[\u4e00-\u9fff]{2,6}/g;
+/** English words plus Chinese character bigrams; no external tokenizer. */
+export function featuresOf(text) {
+    const out = [];
+    for (const match of text.toLowerCase().match(TOKEN_RE) ?? []) {
+        if (/^[a-z]/.test(match)) {
+            if (!STOP_WORDS.has(match))
+                out.push(match);
+            continue;
+        }
+        if (match.length === 2) {
+            if (!STOP_WORDS.has(match))
+                out.push(match);
+            continue;
+        }
+        for (let i = 0; i < match.length - 1; i += 1) {
+            const gram = match.slice(i, i + 2);
+            if (!STOP_WORDS.has(gram))
+                out.push(gram);
+        }
+    }
+    return out;
+}
+export function buildKeywordIndex(docs) {
+    const df = {};
+    const postings = {};
+    for (const doc of docs) {
+        for (const term of new Set(featuresOf(doc.text))) {
+            df[term] = (df[term] ?? 0) + 1;
+            (postings[term] ??= []).push(doc.id);
+        }
+    }
+    return { docCount: docs.length, df, postings };
+}
+export function idf(term, index) {
+    return Math.log((index.docCount + 1) / ((index.df[term] ?? 0) + 1)) + 1;
+}
+/** IDF-weighted feature overlap, normalized so long notes cannot dominate. */
+export function relevance(query, text, index) {
+    const qTerms = [...new Set(featuresOf(query))];
+    const tTerms = new Set(featuresOf(text));
+    if (qTerms.length === 0 || tTerms.size === 0)
+        return 0;
+    let hit = 0;
+    let total = 0;
+    for (const term of qTerms) {
+        const weight = idf(term, index);
+        total += weight;
+        if (tTerms.has(term))
+            hit += weight;
+    }
+    const denominator = Math.sqrt(total * tTerms.size);
+    return denominator > 0 ? Math.min(1, hit / denominator) : 0;
+}

package/lib/core/llm-adapter.d.ts

@@ -0,0 +1,17 @@
+export interface LlmRequest {
+    system: string;
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    tools?: readonly unknown[];
+}
+export interface LlmResult {
+    text: string;
+}
+/** Implemented by the host layer; the core never owns credentials or a client. */
+export interface LlmAdapter {
+    complete(request: LlmRequest): Promise<LlmResult>;
+}
+export declare const disabledLlm: LlmAdapter;
+export declare function isBudgetError(error: unknown): boolean;

package/lib/core/llm-adapter.js

@@ -0,0 +1,8 @@
+export const disabledLlm = {
+    async complete() {
+        throw new Error('LLM adapter is disabled (maintenanceMode: off)');
+    },
+};
+export function isBudgetError(error) {
+    return error?.code === 'MONEY_BUDGET_EXCEEDED';
+}

package/lib/core/llm-reviewer.d.ts

@@ -0,0 +1,25 @@
+import { type LlmAdapter } from './llm-adapter.js';
+import { type ReviewRequest, type ReviewResult, type Reviewer } from './review.js';
+import type { MemoryStore } from './store.js';
+export interface LlmReviewerOptions {
+    companionId?: string;
+    candidateBudget?: number;
+    contextTokens?: number;
+    retryDelayMs?: number;
+    maxNotesPerBatch?: number;
+}
+/**
+ * Turns unprocessed `cold` lines into notes through the host model. The store is
+ * the single writer: notes, the bounded index and the watermark all go through it.
+ * A failed model call backs off instead of re-billing on every idle tick.
+ */
+export declare class LlmReviewer implements Reviewer {
+    private readonly store;
+    private readonly adapter;
+    private readonly options;
+    private lastFailureAt;
+    constructor(store: MemoryStore, adapter: LlmAdapter, options?: LlmReviewerOptions);
+    review(request: ReviewRequest): Promise<ReviewResult>;
+    /** Reads the newest append-only files and keeps lines after the watermark. */
+    private pendingCandidates;
+}

package/lib/core/llm-reviewer.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { estimateTokens } from './disclosure.js';
+import { isBudgetError } from './llm-adapter.js';
+import { operationId, } from './review.js';
+const REVIEW_SYSTEM = `You are a long-term memory curator. From the conversation lines below, extract only durable facts about the user, their explicit preferences, feedback, or ongoing projects.
+Return STRICT JSON only: {"notes":[{"name":"short-slug","description":"one sentence","type":"user|feedback|project|reference","evidence":"verbatim quote from the input","body":"the fact in plain words"}]}
+Rules: one fact per note; evidence must be copied verbatim from the input; never invent or infer emotions; skip greetings, transient tasks, tool output and roleplay; return {"notes":[]} when nothing is worth keeping.`;
+const NOTE_TYPES = ['user', 'feedback', 'project', 'reference'];
+function operationMarker(body) {
+    return /<!-- op: ([a-f0-9]+) -->/.exec(body)?.[1];
+}
+function parseNotes(text) {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    const raw = parsed?.notes;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((item) => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const note = item;
+        const name = String(note.name ?? '').trim().slice(0, 48);
+        const description = String(note.description ?? '').trim().slice(0, 320);
+        const evidence = String(note.evidence ?? '').trim().slice(0, 2000);
+        const body = String(note.body ?? description).trim().slice(0, 12_000);
+        const type = NOTE_TYPES.includes(note.type) ? note.type : 'reference';
+        if (!name || !description || !body || !evidence)
+            return [];
+        return [{ name, description, type, evidence, sourceRefs: [], body }];
+    });
+}
+/**
+ * Turns unprocessed `cold` lines into notes through the host model. The store is
+ * the single writer: notes, the bounded index and the watermark all go through it.
+ * A failed model call backs off instead of re-billing on every idle tick.
+ */
+export class LlmReviewer {
+    store;
+    adapter;
+    options;
+    lastFailureAt = 0;
+    constructor(store, adapter, options = {}) {
+        this.store = store;
+        this.adapter = adapter;
+        this.options = options;
+    }
+    async review(request) {
+        const empty = { notes: [], indexLines: [] };
+        const retryDelay = this.options.retryDelayMs ?? 60_000;
+        if (this.lastFailureAt > 0 && Date.now() - this.lastFailureAt < retryDelay)
+            return empty;
+        const meta = await this.store.readMeta();
+        const candidates = await this.pendingCandidates(meta.lastProcessedSeq);
+        const batch = candidates.slice(0, this.options.candidateBudget ?? 24);
+        if (batch.length === 0)
+            return empty;
+        const budget = this.options.contextTokens ?? 800;
+        const lines = [];
+        let used = 0;
+        for (const item of batch) {
+            const line = `[${item.role}] ${item.content.slice(0, 800)}`;
+            const cost = estimateTokens(line);
+            if (used + cost > budget)
+                break;
+            lines.push(line);
+            used += cost;
+        }
+        if (lines.length === 0)
+            return empty;
+        let answer;
+        try {
+            answer = (await this.adapter.complete({
+                system: REVIEW_SYSTEM,
+                messages: [{ role: 'user', content: lines.join('\n') }],
+            })).text;
+        }
+        catch (error) {
+            this.lastFailureAt = Date.now();
+            meta.lastReviewAt = Date.now();
+            await this.store.writeMeta(meta);
+            if (isBudgetError(error))
+                this.lastFailureAt += retryDelay;
+            return empty;
+        }
+        const parsed = parseNotes(answer).slice(0, this.options.maxNotesPerBatch ?? 8);
+        const companionId = request.companionId || this.options.companionId || 'default';
+        const existing = await this.store.listNotes();
+        const seen = new Set(existing.map((note) => operationMarker(note.body)).filter(Boolean));
+        const indexLines = [...await this.store.readIndex()];
+        const written = [];
+        const today = new Date().toISOString().slice(0, 10);
+        for (const note of parsed) {
+            const payloadHash = createHash('sha256').update(JSON.stringify(note)).digest('hex');
+            const opId = operationId(companionId, batch[0].id, batch[0].seq, payloadHash);
+            if (seen.has(opId))
+                continue;
+            const safeName = note.name.replace(/[\\/:*?"<>|\r\n]/g, '_');
+            const frontmatter = {
+                name: safeName,
+                description: note.description,
+                type: note.type,
+                created: today,
+                updated: today,
+                evidence: note.evidence,
+                sourceRefs: batch.slice(0, 4).map((item) => item.id),
+                supersededBy: null,
+                confidence: 0.7,
+                strength: 0.6,
+                lastAccess: Date.now(),
+                accessCount: 0,
+                pinned: false,
+                state: 'active',
+            };
+            const id = await this.store.writeNote(frontmatter, `${note.body}\n\n<!-- op: ${opId} -->`);
+            const line = `- [${safeName}](notes/${id}) — ${note.description.slice(0, 80)}`;
+            if (!indexLines.includes(line))
+                indexLines.push(line);
+            written.push(note);
+            seen.add(opId);
+        }
+        if (written.length > 0)
+            await this.store.writeIndex(indexLines);
+        meta.lastProcessedSeq = Math.max(meta.lastProcessedSeq, ...batch.map((item) => item.seq));
+        meta.lastReviewAt = Date.now();
+        await this.store.writeMeta(meta);
+        return { notes: written, indexLines };
+    }
+    /** Reads the newest append-only files and keeps lines after the watermark. */
+    async pendingCandidates(afterSeq) {
+        const files = await readdir(this.store.paths.cold).catch(() => []);
+        const found = [];
+        for (const file of files.filter((name) => name.endsWith('.jsonl')).sort().slice(-3)) {
+            const text = await readFile(join(this.store.paths.cold, file), 'utf8').catch(() => '');
+            for (const line of text.split(/\r?\n/).filter(Boolean)) {
+                try {
+                    const record = JSON.parse(line);
+                    if (typeof record.seq === 'number' && record.seq > afterSeq
+                        && typeof record.content === 'string' && record.content.trim()) {
+                        found.push(record);
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        return found.sort((a, b) => a.seq - b.seq);
+    }
+}