soulbridge 0.0.26 → 0.0.98

package/dist/packages/core/src/index.js

@@ -9,18 +9,67 @@ export { openSqlite, SCHEMA_VERSION, AFFECT_RETENTION_MS, DbNewerThanBinaryError
 export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT_WINDOW_MS, } from './context.js';
 export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule, detectCorrection, isQuestion, } from './reflect.js';
 export { rank, scoreMemory, tokenize, relevance, bm25, buildCorpusStats } from './scoring.js';
+export { parseThreadLine } from './extract.js';
+export { renderConsolidationPrompt, renderVerificationPrompt, renderRelationPrompt, renderRuleClassifyPrompt, renderProfileMergePrompt, renderExtractionPrompt, } from './prompts.js';
+export { gateConclusion, conclusionSlots, normalizeStatement, parseConclusionDraft, parseVerificationDraft, parseRelationDraft, readVerification, parseProfileMerge, groupProfileCandidates, isDerivedProfileLine, PROFILE_DIMENSIONS, } from './consolidate.js';
+export { fires, parseRuleClassifications, parseTrigger, selectRules } from './rules.js';
+export { planRetrieval } from './retrieval.js';
 export * from './affect/index.js';
+export { escapeBlockText, escapeAttr } from './inject-text.js';
 export { measureStyle } from './style/measure.js';
 export * from './storage/config.js';
 export * from './storage/merge.js';
 export * from './storage/steering.js';
 export * from './storage/transcript.js';
+import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
+import { HOLDER_WORDS } from './config/domains.js';
+import { isActive, isRetracted, roleOf } from './roles.js';
+import { parseTrigger } from './rules.js';
+import { planRetrieval } from './retrieval.js';
+import { gateConclusion, conclusionSlots, isDerivedProfileLine, PROFILE_DIMENSIONS } from './consolidate.js';
 import { buildContext } from './context.js';
 import { reflect, ruleExtract, nextEmotion } from './reflect.js';
 import { rank, tokenize } from './scoring.js';
 import { analyzeAffect, emptyAffect, lexiconAnalyzer } from './affect/analyze.js';
-import { gateDrafts, llmExtractTurn } from './reflect.js';
+import { extractByRules, extractWithModel } from './extract.js';
 export { gateDrafts } from './reflect.js';
+/** The fact type a legacy MemoryType maps to. One vocabulary at rest: type_name. */
+const MEMORY_TYPE_TO_FACT = {
+    semantic: '事实',
+    episodic: '事件',
+    strategy: '教训',
+    cognition: '原则',
+    relationship: '关系',
+    trait: '性格',
+    fact: '事实',
+};
+/** Longest statement accepted from a host; matches the extractor's ceiling. */
+const MAX_FACT_CHARS = 200;
+/**
+ * Read a fact as the shape `recall()` has always returned.
+ *
+ * Callers (the adapter's `soul_recall` tool) only read id/type/content/score, but the
+ * type must stay honest: return the fact's own type name rather than inventing a
+ * MemoryType it never had.
+ */
+function factAsMemory(fact) {
+    return {
+        id: fact.id,
+        soulId: fact.soulId,
+        userId: fact.userId,
+        type: 'fact',
+        content: fact.statement,
+        importance: Math.round(fact.confidence * 10),
+        vividness: 0.8,
+        recallCount: fact.recallCount ?? 0,
+        status: 'active',
+        visibility: 'private',
+        keywords: tokenize(fact.statement),
+        createdAt: fact.createdAt,
+        lastRecalledAt: fact.lastRecalledAt,
+        updatedAt: fact.createdAt,
+    };
+}
 export class Soul {
     store;
     soulId;
@@ -53,29 +102,29 @@ export class Soul {
     }
     /** Verb 1: session start. */
     context(request = {}) {
+        // Spread, not a field list: an explicit list silently dropped every option
+        // added later (includeAnchors stayed dead for a whole release).
         return buildContext(this.store, {
+            ...request,
             soulId: this.soulId,
             userId: this.userId,
-            query: request.query,
-            maxChars: request.maxChars,
-            track: request.track,
-            types: request.types,
-            minImportance: request.minImportance,
-            maxItems: request.maxItems,
         });
     }
     /**
      * Audit view: every non-deleted row, including superseded and expired ones.
      * Prompt builders use `context`, which filters both out.
      */
+    /**
+     * The recent holdings, as the shape hosts already consume.
+     *
+     * Reads facts: the legacy table is inert after the migration, and a list that kept
+     * reading it would look empty while the system clearly remembers things.
+     */
     list(limit = 50) {
-        return this.store.query({
-            soulId: this.soulId,
-            userId: this.userId,
-            status: ['active', 'superseded'],
-            includeExpired: true,
-            limit,
-        });
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit })
+            .filter((fact) => isActive(fact))
+            .map(factAsMemory);
     }
     /** Tombstone one memory so it never reaches a prompt again. */
     forget(id) {
@@ -107,6 +156,33 @@ export class Soul {
     corrections(limit = 20) {
         return this.store.recentCorrections(this.soulId, this.userId, limit);
     }
+    /**
+     * Was this turn one the user corrected?
+     *
+     * A correction is the highest-signal moment a lesson has: being told you were
+     * wrong is the consequence the experience comes with (brief 0023, T1). The link
+     * is the user's own words — corrections do not carry a turn id, and inventing a
+     * time window would misattribute a nearby turn.
+     */
+    wasCorrectedTurn(turnId) {
+        const turn = this.store.turn(turnId);
+        const text = (turn?.userText ?? '').trim();
+        if (!text)
+            return false;
+        return this.store
+            .recentCorrections(this.soulId, this.userId, 50)
+            .some((correction) => (correction.userText ?? '').trim() === text);
+    }
+    /**
+     * The experiences of one turn that were flagged as lessons, and nothing else.
+     *
+     * Promotion reads the flag, never the statement: whether a sentence is "about how
+     * to work" is the semantic call the extractor already made, and re-deriving it in
+     * code would be the guess ADR 0027 forbids.
+     */
+    promotionCandidates(turnId) {
+        return this.store.factsByTurns([turnId]).filter((fact) => fact.slots.some((slot) => slot.slot === '原则候选' && slot.value.kind === 'text' && slot.value.value === '是'));
+    }
     /**
      * Store one exchange (RFC 0007). Idempotent on `(sessionId, turn)`: a repeat is
      * ignored by the store, so this returns nothing — there is no id worth handing
@@ -114,8 +190,11 @@ export class Soul {
      */
     recordTurnPair(input) {
         const at = input.at ?? Date.now();
+        // The generated id is the row id in `turns`; callers must use it for
+        // facts.source_turn_id, otherwise a hook cannot expand back to its turn.
+        const id = `tp_${at.toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
         this.store.putTurnPair({
-            id: `tp_${at.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+            id,
             soulId: this.soulId,
             userId: this.userId,
             sessionId: input.sessionId,
@@ -125,7 +204,19 @@ export class Soul {
             assistantText: input.assistantText,
             metadata: input.metadata ?? {},
             createdAt: at,
-        });
+        }, input.steps);
+        // A repeat is dropped by the unique (session, turn) index, so the generated id
+        // may be a phantom. Return the id that is actually stored: the caller enqueues
+        // extraction with it, and a phantom id made the queue drop the turn as missing.
+        return this.store.turnByTurnNo(input.sessionId, input.turn)?.id ?? id;
+    }
+    /**
+     * One turn by id, for adapters that only kept the id (extraction queue,
+     * handoff). Returns null when the row is gone, so callers can drop the item
+     * instead of retrying forever.
+     */
+    turn(id) {
+        return this.store.turn(id);
     }
     /** Recall exchanges, scored against `query` when it is non-empty. */
     recallTurnPairs(query, limit = 5) {
@@ -139,87 +230,806 @@ export class Soul {
     countTurnPairs() {
         return this.store.countTurnPairs(this.soulId, this.userId);
     }
-    /** Verb 3: on demand. */
-    recall(query, limit = 5) {
-        const memories = this.store.query({ soulId: this.soulId, userId: this.userId });
-        const ranked = rank(memories, query, Date.now()).slice(0, limit);
-        this.store.touch(ranked.map((r) => r.memory.id));
-        return ranked;
+    /**
+     * Every turn that matches, not the best few: for "how many times" and "what
+     * did we decide overall" the count matters more than the ranking, and the
+     * model does the counting (ADR 0027). `truncated` tells the caller the answer
+     * would be incomplete.
+     */
+    /* ---------------- the model proper (spec/model.v0.md) ---------------- */
+    /**
+     * Turn text → drafts.
+     *
+     * Extraction is the model's job (ADR 0029: Generative Agents, Mem0 and
+     * Graphiti all extract with an LLM and keep code for validation and storage).
+     * The rules are a floor, not a ceiling: they matter when no model is
+     * configured and they cross-check the answer when one is. A model answer with
+     * no usable draft falls back to the rules instead of losing the turn.
+     */
+    async extract(text, options = {}) {
+        const at = options.at ?? Date.now();
+        const byRules = extractByRules(text, at);
+        // No length gate here: "做" and "重来" are one and two characters and are
+        // real decisions. The host decides what is worth a model call; core only
+        // reports which path it took.
+        if (options.mode === 'rules')
+            return { ...byRules, reason: 'rules-mode' };
+        if (!options.llm)
+            return { ...byRules, reason: 'no-model' };
+        // The model has to know what is already stored, or it cannot reuse a name
+        // and cannot tell that new information contradicts an old fact.
+        const context = options.context ?? this.extractionContext();
+        // A parse failure is unreadable without the text the model actually sent:
+        // "model-failed" alone hid a 54-character reply for an hour today.
+        const wrapped = this.onLlmRaw
+            ? async (prompt) => {
+                const raw = await options.llm(prompt);
+                this.onLlmRaw(raw);
+                return raw;
+            }
+            : options.llm;
+        const result = await extractWithModel(text, wrapped, at, context, options.assistantText);
+        return result.draft ?? { ...byRules, reason: `model-${result.error ? 'failed' : 'empty'}` };
     }
-    /** Pure analysis, no storage. Async because the analyzer may call a model. */
-    async analyze(text) {
-        return this.analyzeTurn(text);
+    /** The slice of the store the extractor is allowed to know about. */
+    extractionContext(limit = 20, options = {}) {
+        const entities = this.store
+            .findEntities({ soulId: this.soulId, userId: this.userId, limit })
+            .map((e) => ({
+            id: e.id,
+            name: e.name,
+            aliases: e.aliases,
+            relation: typeof e.attrs.relation === 'string' ? e.attrs.relation : undefined,
+        }));
+        const facts = this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 12 })
+            .map((f) => ({ id: f.id, statement: f.statement, atText: f.atText }));
+        // Candidate threads, most recently used first. "How many turns ago" is what
+        // lets the model tell "just now" from "a while back" without counting. Each
+        // candidate also carries its last lines: a label cannot answer "does this turn
+        // continue that conversation", and continuing is now the default (ADR 0034).
+        const threads = this.store.openThreads(this.soulId, this.userId, 5).map((thread) => {
+            const turns = this.store.threadTurns(thread.id).slice(-2);
+            const recent = turns.flatMap((turn) => {
+                const lines = [];
+                if (turn.userText.trim())
+                    lines.push({ role: 'user', text: turn.userText });
+                if (turn.assistantText.trim())
+                    lines.push({ role: 'assistant', text: turn.assistantText });
+                return lines;
+            });
+            return {
+                id: thread.id,
+                topic: thread.topic,
+                ago: options.turnNo !== undefined && thread.lastTurnNo !== undefined
+                    ? Math.max(0, options.turnNo - thread.lastTurnNo)
+                    : undefined,
+                recent: recent.slice(-3),
+            };
+        });
+        // The previous user line is what "继续 / 那个 / 她" refers to. Extraction is per
+        // turn; without it the model has nothing to bind to.
+        const previousUserText = options.sessionId !== undefined && options.turnNo !== undefined
+            ? (this.store.previousTurnText(options.sessionId, options.turnNo) ?? undefined)
+            : undefined;
+        return { entities, facts, threads, previousUserText };
     }
     /**
-     * Verb 2: after each turn.
+     * Put a turn into a thread.
      *
-     * The analyzer may be async (a model); any failure degrades to the lexicon
-     * analyzer. Emotion is computed from the turn only — never from affect.
+     * Default is continuity (ADR 0034): a named thread joins when it exists and is open;
+     * an unreadable answer, a hallucinated id, or no answer at all joins the previous
+     * turn's thread instead of opening a new one — fragmentation is what starves
+     * consolidation, and threads can be split later while a lost topic cannot.
      */
-    async observe(turn) {
-        const now = turn.at ?? Date.now();
-        const affect = turn.role === 'user' ? await this.analyzeTurn(turn.content) : emptyAffect();
-        // Rules first: they are precise and cheap. Only when they find nothing does
-        // the optional model get a chance, so it can add recall without overriding
-        // a rule that already fired.
-        let drafts = ruleExtract([turn]);
-        let extractedBy = drafts.length > 0 ? 'rules' : 'none';
-        // A model that says "nothing to keep" and a model that answers garbage used
-        // to be indistinguishable; keep them apart for measurement.
-        let llmOutcome = this.llm
-            ? 'skipped-rules'
-            : 'off';
-        if (drafts.length === 0 && turn.role === 'user' && this.llm) {
-            if (turn.content.length <= this.llmMaxChars) {
-                try {
-                    const draft = await llmExtractTurn(turn.content, this.llm, this.onLlmRaw);
-                    if (draft) {
-                        drafts = [draft];
-                        extractedBy = 'llm';
-                        llmOutcome = 'stored';
-                    }
-                    else {
-                        llmOutcome = 'null';
-                    }
+    applyThread(attribution, spec) {
+        const join = (id, reason, nextTopic) => {
+            const thread = this.store.thread(id);
+            if (!thread || thread.status !== 'open')
+                return null;
+            this.store.attachTurn(spec.turnId, thread.id);
+            this.store.touchThread(thread.id, spec.turnNo);
+            // A continued thread may have moved on within itself: keep the label honest.
+            const topic = nextTopic?.trim();
+            const updated = Boolean(topic) && topic !== thread.topic;
+            if (updated)
+                this.store.updateThreadTopic(thread.id, topic);
+            return {
+                threadId: thread.id,
+                created: false,
+                topic: updated ? topic : thread.topic,
+                joinReason: reason,
+                topicUpdated: updated,
+            };
+        };
+        if (attribution?.kind === 'continue') {
+            const existing = join(attribution.id, 'continue', attribution.topic);
+            if (existing)
+                return existing;
+            // A named thread that does not exist (or is closed) is not evidence for a new
+            // topic — fall through to the previous thread, then to a new one.
+        }
+        if (attribution?.kind === 'new') {
+            return this.openThreadFor(spec, 'explicit-new', attribution.topic);
+        }
+        if (spec.previousThreadId) {
+            const previous = join(spec.previousThreadId, 'fallback-previous');
+            if (previous)
+                return previous;
+        }
+        // `attribution === undefined` covers "无" and unparseable output.
+        return this.openThreadFor(spec, attribution?.kind === 'continue' ? 'fallback-unknown-id' : 'no-context');
+    }
+    openThreadFor(spec, joinReason, topicFromModel) {
+        const topic = topicFromModel ?? spec.fallbackTopic ?? '未命名话题';
+        const thread = this.store.openThread({
+            soulId: this.soulId,
+            userId: this.userId,
+            sessionId: spec.sessionId,
+            // Whole topic: a label cut at 20 characters loses the end, which is where the
+            // qualifier usually sits. The prompt asks for one short sentence; storage does
+            // not cut one (ADR 0034 keeps truncation out of evidence).
+            topic,
+            openedAt: spec.at,
+            turnNo: spec.turnNo,
+        });
+        this.store.attachTurn(spec.turnId, thread.id);
+        return { threadId: thread.id, created: true, topic: thread.topic, joinReason, topicUpdated: false };
+    }
+    /**
+     * Drafts → database.
+     *
+     * The gate is a labeller, not a filter. A sentence that parses is kept: an
+     * undeclared entity in a slot is kept as text (no entity is created), an unknown
+     * holder falls back to the world layer, and only an unreadable statement or an
+     * exact duplicate is refused. Everything degraded or refused is reported, so the
+     * loss is visible instead of silent.
+     */
+    commitDrafts(draft, options = {}) {
+        const entities = new Map();
+        const skipped = [];
+        const droppedSlots = [];
+        const holderFallbacks = [];
+        const at = options.at ?? Date.now();
+        // One entity per name, whatever its declared type: the same 核桃 appearing as
+        // both person and thing splits every recall that mentions it. Existing rows
+        // win, so a wrongly typed first sighting is reused rather than duplicated.
+        // Aliases are the same entity: without them "阿林" reads as undeclared and the
+        // slot degrades to text even though the person is known.
+        const byName = new Map();
+        for (const known of this.store.findEntities({ soulId: this.soulId, userId: this.userId, limit: 500 })) {
+            if (!byName.has(known.name))
+                byName.set(known.name, known);
+            for (const alias of known.aliases ?? []) {
+                if (alias && !byName.has(alias))
+                    byName.set(alias, known);
+            }
+        }
+        const declared = new Set(draft.entities.map((entity) => entity.name));
+        // No default type: choosing person/thing is a meaning decision, and a default here
+        // would let the code make it silently (ADR 0027, health-check §12). Every caller
+        // passes the type the model declared.
+        const ensureEntity = (name, type) => {
+            const existing = byName.get(name);
+            if (existing)
+                return existing;
+            const key = `${type}:${name}`;
+            const pending = entities.get(key);
+            if (pending)
+                return pending;
+            const written = this.store.putEntity({
+                soulId: this.soulId,
+                userId: this.userId,
+                type,
+                name,
+                seenAt: at,
+                attrs: draft.entities.find((e) => e.name === name)?.attrs,
+                aliases: draft.entities.find((e) => e.name === name)?.aliases,
+            });
+            entities.set(key, written);
+            byName.set(name, written);
+            return written;
+        };
+        for (const draftEntity of draft.entities)
+            ensureEntity(draftEntity.name, draftEntity.type);
+        const facts = [];
+        // Declared before writeFact: a fact whose time is unknown opens a gap inside it.
+        const gaps = [];
+        const recent = this.store.facts({ soulId: this.soulId, userId: this.userId, limit: 50 });
+        /** One gate for every write path: legacy facts and operation payloads share it. */
+        const writeFact = (factDraft) => {
+            const statement = factDraft.statement.trim();
+            if (!statement) {
+                skipped.push({ what: 'fact', reason: 'empty statement' });
+                return null;
+            }
+            // Every readable sentence is kept. The gate used to reject a fact when one of
+            // its slots named an undeclared entity (40 of 45 refusals in a live trace) or
+            // when it had no slot and no time (5 more) — one bad slot deleted the sentence.
+            //
+            // A slot names an entity only when that name was declared or is already known.
+            // Otherwise the words are kept as text: the sentence survives, the store does
+            // not fill up with "仅在电话里说" as a person, and nothing is invented.
+            const slots = [];
+            for (const slot of factDraft.slots) {
+                if (slot.value.kind !== 'entity') {
+                    slots.push({ slot: slot.slot, value: slot.value });
+                    continue;
                 }
-                catch {
-                    // The model is an enhancement; a transport or parse failure leaves the
-                    // rule result (nothing) in place.
-                    llmOutcome = 'failed';
+                const name = slot.value.entityName.trim();
+                // Only a declared or already-known name is a reference; the declaration carries
+                // the type, so the code never has to guess one.
+                const known = byName.get(name);
+                const fromDraft = declared.has(name) ? draft.entities.find((entity) => entity.name === name) : undefined;
+                const type = known?.type ?? fromDraft?.type;
+                if (fromDraft || known) {
+                    const entity = known ?? ensureEntity(name, type);
+                    slots.push({ slot: slot.slot, value: { kind: 'entity', entityId: entity.id } });
+                    continue;
                 }
+                slots.push({ slot: slot.slot, value: { kind: 'text', value: name } });
+                droppedSlots.push({ fact: statement, slot: slot.slot, value: name });
             }
-            else {
-                llmOutcome = 'skipped-long';
+            // Where the fact holds (ADR 0032): `world`, `self`, or a named mind. The holder is
+            // a reference to an entity that already exists (declared entities are created
+            // above), never a new entity created from a holder string.
+            const holderName = factDraft.holder?.trim() || HOLDER_WORDS[0];
+            let holder = HOLDER_WORDS[0];
+            if (holderName !== HOLDER_WORDS[0]) {
+                if (holderName === HOLDER_WORDS[1]) {
+                    holder = HOLDER_WORDS[1];
+                }
+                else {
+                    const holderEntity = byName.get(holderName);
+                    if (holderEntity)
+                        holder = holderEntity.id;
+                    else
+                        holderFallbacks.push({ fact: statement, holder: holderName });
+                }
+            }
+            const duplicated = recent.some((f) => f.statement === statement &&
+                (f.atText ?? '') === (factDraft.atText ?? '') &&
+                Math.abs((f.at ?? f.createdAt) - (factDraft.at ?? at)) < 86400000);
+            if (duplicated) {
+                skipped.push({ what: statement, reason: 'duplicate' });
+                return null;
+            }
+            // The promotion rules read this slot; they must not re-read the statement to
+            // guess whether it was a lesson, because that is the semantic call the model
+            // already made.
+            if (factDraft.principle)
+                slots.push({ slot: '原则候选', value: { kind: 'text', value: '是' } });
+            // ADR 0035: a fact from my side of the exchange is `inferred`, and inferred
+            // claims must carry their evidence. The turn id is the evidence available here —
+            // claims that need a tool or test result are kept out by the prompt instead.
+            if (factDraft.source === 'inferred' && options.turnId && !slots.some((slot) => slot.slot === '依据')) {
+                slots.push({ slot: '依据', value: { kind: 'text', value: options.turnId } });
+            }
+            const written = this.store.putFact({
+                soulId: this.soulId,
+                userId: this.userId,
+                statement,
+                holder,
+                typeName: factDraft.typeName,
+                at: factDraft.at,
+                atText: factDraft.atText,
+                atPrecision: factDraft.atPrecision,
+                source: factDraft.source,
+                confidence: factDraft.confidence,
+                sourceTurnId: options.turnId,
+                slots,
+            });
+            facts.push(written);
+            // Known to have happened, unknown when: keep the memory and turn the missing
+            // date into something to ask about later, instead of inventing one.
+            if (holder === 'world' && written.atPrecision === 'unknown') {
+                const subject = slots.find((slot) => slot.value.kind === 'entity');
+                gaps.push(this.store.putGap({
+                    soulId: this.soulId,
+                    userId: this.userId,
+                    aboutEntityId: subject?.value.kind === 'entity' ? subject.value.entityId : undefined,
+                    aboutFactId: written.id,
+                    // Whole statement: the gap asks "when did this happen", so the sentence it
+                    // refers to cannot be a prefix of itself.
+                    topic: `日期不明：${statement}`,
+                    tension: 0.3,
+                    openedAt: at,
+                }));
+            }
+            return written;
+        };
+        // Operations carry the merge decision (Mem0's ADD/UPDATE/DELETE); plain facts are
+        // the legacy shape and every one of them is an add.
+        // `validateDraft` always returns an operations array, so `??` alone left it empty
+        // and every legacy fact was written nowhere — silently, with no skipped entry.
+        const operations = draft.operations && draft.operations.length > 0
+            ? draft.operations
+            : draft.facts.map((fact) => ({ op: 'add', fact }));
+        for (const operation of operations) {
+            if (operation.op === 'noop')
+                continue;
+            const written = writeFact(operation.fact);
+            if (!written)
+                continue;
+            if (operation.op === 'supersede' || operation.op === 'update') {
+                // The model may name any id; only a row we actually hold may be retired. A
+                // missing target degrades to a plain add and is reported — the sentence is never
+                // lost, and "the fact changed" is never claimed without a real predecessor.
+                const target = operation.targetId ? this.store.fact(operation.targetId) : null;
+                const sameScope = target && target.soulId === this.soulId && target.userId === this.userId;
+                if (target && sameScope && target.status !== 'superseded') {
+                    this.store.supersedeFact(target.id, written.id);
+                }
+                else {
+                    skipped.push({
+                        what: written.statement,
+                        reason: target ? `supersede-target-${target.status}` : `unknown-supersede-target: ${operation.targetId ?? '(missing)'}`,
+                    });
+                }
             }
         }
-        // Deterministic write gates: shape -> semantics -> per-turn budget. Whatever
-        // they refuse is reported, so written: 0 always has a reason.
-        const gated = gateDrafts(drafts);
-        // observe runs every turn; repeating a sentence must not create a second row.
-        const seen = new Set(this.store.query({ soulId: this.soulId, userId: this.userId, limit: 10_000 }).map((m) => m.content.trim()));
-        let written = 0;
-        for (const draft of gated.accepted) {
-            if (seen.has(draft.content.trim()))
+        for (const gapDraft of draft.gaps) {
+            // A gap about a known entity only; no type guessing, and no entity minted from a
+            // gap's wording (that is how "仅在电话里说" became a person).
+            const about = gapDraft.aboutEntityName ? byName.get(gapDraft.aboutEntityName) : undefined;
+            gaps.push(this.store.putGap({
+                soulId: this.soulId,
+                userId: this.userId,
+                aboutEntityId: about?.id,
+                aboutFactId: facts.length === 1 ? facts[0].id : undefined,
+                topic: gapDraft.topic,
+                tension: gapDraft.tension,
+                openedAt: at,
+            }));
+        }
+        return { entities: [...entities.values()], facts, gaps, skipped, droppedSlots, holderFallbacks };
+    }
+    /** Remember a person/thing/place; calling again just refreshes "last mentioned". */
+    rememberEntity(name, 
+    // No default type: person/thing/place is a meaning decision, and a default would let
+    // every caller silently decide "person" (ADR 0027, health-check §9.5).
+    type, options = {}) {
+        return this.store.putEntity({
+            soulId: this.soulId,
+            userId: this.userId,
+            type,
+            name,
+            aliases: options.aliases,
+            attrs: options.attrs,
+            seenAt: options.seenAt,
+        });
+    }
+    findEntities(name, limit = 20) {
+        return this.store.findEntities({ soulId: this.soulId, userId: this.userId, name, limit });
+    }
+    /** Write one connection between things. */
+    recordFact(spec) {
+        return this.store.putFact({ ...spec, soulId: this.soulId, userId: this.userId });
+    }
+    /**
+     * Store one conclusion if the deterministic gate accepts it.
+     *
+     * A conclusion is not a new kind of record: it is a fact whose type is 结论,
+     * held by the soul itself, with one `fact` slot per citation. That way recall,
+     * export and supersede keep working, and the evidence can be followed back to
+     * the observation that produced it.
+     */
+    recordConclusion(draft, options) {
+        const allowed = new Set(options.allowed);
+        // A restatement is merged, not written again: the held conclusion keeps its
+        // wording and gains the evidence, so it gets stronger instead of duplicated.
+        // Only evidence from this batch counts — a merge must be backed the same way
+        // a new conclusion would be.
+        if (options.mergeInto) {
+            const evidence = draft.evidence.filter((id) => allowed.has(id));
+            if (evidence.length >= 2) {
+                const merge = this.mergeEvidence(options.mergeInto, evidence);
+                if (merge.ok)
+                    return { ok: true, merged: options.mergeInto };
+                // A merge target that moved on is not an error; fall through and write the
+                // conclusion normally rather than losing it.
+            }
+        }
+        const old = draft.supersedes ? this.store.fact(draft.supersedes) : null;
+        const gate = gateConclusion({ draft, allowed, existing: old });
+        if (!gate.ok)
+            return { ok: false, reason: gate.reason };
+        const fact = this.store.putFact({
+            soulId: this.soulId,
+            userId: this.userId,
+            statement: gate.statement,
+            typeName: '结论',
+            holder: 'self',
+            confidence: gate.confidence,
+            slots: conclusionSlots(gate.evidence, this.entitiesOfFacts(gate.evidence)),
+        });
+        // Superseding an unknown row would silently claim a revision that never
+        // happened; the gate already checked the target is a conclusion we hold.
+        let superseded;
+        if (old?.typeName === '结论') {
+            this.store.supersedeFact(old.id, fact.id);
+            superseded = old.id;
+        }
+        return { ok: true, fact, superseded };
+    }
+    /**
+     * The rules we hold (ADR 0033): facts whose type is 规则 and whose 触发 slot parses.
+     *
+     * A rule without a usable trigger is skipped, not injected — an always-on rule is
+     * wallpaper, and wallpaper is how a lesson gets ignored.
+     */
+    rules() {
+        const out = [];
+        for (const fact of this.store.facts({ soulId: this.soulId, userId: this.userId, limit: 500 })) {
+            if (roleOf(fact) !== 'rule' || !isActive(fact))
+                continue;
+            const triggerSlot = fact.slots.find((slot) => slot.slot === '触发' && slot.value.kind === 'text');
+            const trigger = parseTrigger(triggerSlot?.value.kind === 'text' ? triggerSlot.value.value : '');
+            if (!trigger)
                 continue;
-            seen.add(draft.content.trim());
-            written += 1;
-            this.store.put({
-                id: `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+            out.push({
+                id: fact.id,
+                statement: fact.statement,
+                trigger,
+                confidence: fact.confidence,
+            });
+        }
+        return out;
+    }
+    /**
+     * Apply a rule classification (ADR 0033): retag as 规则 and store its trigger.
+     *
+     * The trigger is what makes the rule injectable later; a rule without one would
+     * have to be always-on, which is exactly what this split exists to avoid.
+     */
+    markRule(factId, classification) {
+        this.store.setFactTypeName(factId, '规则');
+        const slots = [
+            { slot: '触发', value: { kind: 'text', value: classification.trigger } },
+        ];
+        if (classification.action)
+            slots.push({ slot: '动作', value: { kind: 'text', value: classification.action } });
+        this.store.addSlots(factId, slots);
+    }
+    /** Apply a profile classification: it is about the person, not a triggered rule. */
+    markProfile(factId, options = {}) {
+        this.store.setFactTypeName(factId, '画像');
+        // The dimension is written here because this is the moment the model decided
+        // which lens the judgment belongs to. The merge step cuts its batches along
+        // this value later, so a missing dimension is a judgment that can never be
+        // merged — visible in the merge log as 未标注, not silently guessed.
+        const dimension = options.dimension;
+        if (dimension && PROFILE_DIMENSIONS.includes(dimension)) {
+            this.store.addSlots(factId, [{ slot: '维度', value: { kind: 'text', value: dimension } }]);
+        }
+    }
+    /**
+     * Park a lesson that could not be classified.
+     *
+     * Neither bucket is safe for it: as a rule it would fire every turn, and as a
+     * profile line it would put an imperative into the description of a person. It
+     * goes to 待修, which nothing injects, and shows up in a review count.
+     */
+    markUnclassified(factId) {
+        this.store.setFactTypeName(factId, '待修');
+    }
+    /** The judgments about the person that are waiting to be merged. */
+    profileItems(limit = 60) {
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 500 })
+            .filter((fact) => roleOf(fact) === 'profile' &&
+            isActive(fact) &&
+            // A line that cites sources is derived: merging it again compresses a
+            // compression, and the second round is thinner than the first.
+            !isDerivedProfileLine(fact))
+            .slice(0, limit);
+    }
+    /**
+     * Replace a pile of judgments with the merged ones.
+     *
+     * Each merged line becomes a 画像 fact citing its sources, and every source it
+     * covers is superseded — not deleted, so the audit trail survives the compression.
+     */
+    applyProfileMerge(lines) {
+        const written = [];
+        for (const line of lines) {
+            const fact = this.store.putFact({
                 soulId: this.soulId,
                 userId: this.userId,
-                type: draft.type,
-                content: draft.content,
-                importance: draft.importance,
-                vividness: 0.8,
-                recallCount: 0,
-                status: 'active',
-                visibility: 'private',
-                keywords: tokenize(draft.content),
-                createdAt: now,
-                updatedAt: now,
-                validFrom: now,
+                statement: line.statement,
+                typeName: '画像',
+                holder: 'self',
+                // More sources means more observations behind the line, so it ranks first.
+                confidence: Math.min(0.95, 0.6 + 0.05 * line.sources.length),
+                slots: [
+                    ...line.sources.map((id) => ({ slot: '来源', value: { kind: 'fact', factId: id } })),
+                    // A merged line is not an original: re-merging merged lines loses detail.
+                    { slot: '合并', value: { kind: 'text', value: '1' } },
+                    { slot: '维度', value: { kind: 'text', value: line.dimension } },
+                ],
             });
+            written.push(fact);
+            for (const sourceId of line.sources) {
+                const source = this.store.fact(sourceId);
+                if (source && isActive(source))
+                    this.store.supersedeFact(sourceId, fact.id);
+            }
+        }
+        return written;
+    }
+    /** The merged profile, strongest first — what is injected every turn. */
+    profile(limit = 8) {
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 500 })
+            .filter((fact) => roleOf(fact) === 'profile' && isActive(fact))
+            .sort((a, b) => b.confidence - a.confidence || b.createdAt - a.createdAt)
+            .slice(0, limit);
+    }
+    /** Which primitive this question needs (0020).
+     *
+     * The subject is resolved against the entities we hold, so "上次和 a 吃饭" can
+     * never be answered with the last closed topic.
+     */
+    planRetrieval(text) {
+        // Only people and places can be a question's subject. A concept entity like 情绪
+        // or a product like dsh matches ordinary technical messages, and routing to it
+        // suppresses the related-conversation block — which is how "把 package.json 改
+        // 一下" ended up asking about entity "a".
+        const names = this.store
+            .findEntities({ soulId: this.soulId, userId: this.userId, limit: 500 })
+            .filter((entity) => entity.type === 'person' || entity.type === 'place' || entity.type === 'self')
+            .map((entity) => entity.name);
+        return planRetrieval(text, names);
+    }
+    /** The entity timeline: what is known about one person/thing, newest first. */
+    latestAbout(entityName, options = {}) {
+        return this.store.latestAbout(this.soulId, this.userId, entityName, options);
+    }
+    /** Mark facts as surfaced; retrieval practice slows their decay (0019). */
+    recordRecalls(factIds, at = Date.now()) {
+        this.store.recordRecalls(factIds, at);
+    }
+    /**
+     * Close topics the conversation has moved past.
+     *
+     * Three signals, in order of strength: the host's archive list (the user said
+     * this session is done), turns elapsed inside the running session, and — only
+     * as a fallback — silence in another session.
+     */
+    closeIdleThreads(sessionId, options = {}) {
+        return this.store.closeIdleThreads(this.soulId, this.userId, sessionId, options.idleTurns ?? 6, options.idleMs ?? 24 * 60 * 60_000, options.archivedSessionIds ?? [], options.at ?? Date.now());
+    }
+    /** The thread the previous turn belonged to, for the attribution candidate list. */
+    threadBefore(sessionId, turnNo) {
+        return this.store.threadBefore(sessionId, turnNo);
+    }
+    /**
+     * Everything a closed thread needs for consolidation: the topic, the turns in
+     * order (as text), and the facts extracted from those turns.
+     *
+     * The turns are what makes this a chapter rather than a batch: A B A means the
+     * facts alone have lost the resume.
+     */
+    threadContext(threadId) {
+        const thread = this.store.thread(threadId);
+        if (!thread)
+            return null;
+        const turns = this.store.threadTurns(threadId);
+        const facts = this.store.factsByTurns(turns.map((turn) => turn.id));
+        return {
+            thread,
+            turns: turns.map((turn) => ({ turnNo: turn.turn, userText: turn.userText, assistantText: turn.assistantText })),
+            facts,
+        };
+    }
+    /**
+     * What "where were we" means: the last topic that actually finished, its
+     * conclusion, and the last couple of turns.
+     *
+     * A session boundary is not a topic boundary, so this is keyed on the closed
+     * thread, not on the previous session.
+     */
+    lastClosedThread() {
+        const thread = this.store.lastClosedThread(this.soulId, this.userId);
+        if (!thread)
+            return null;
+        const conclusion = thread.summaryFactId ? this.store.fact(thread.summaryFactId) : null;
+        const turns = this.store
+            .threadTurns(thread.id)
+            .slice(-2)
+            .map((turn) => ({ turnNo: turn.turn, userText: turn.userText, assistantText: turn.assistantText }));
+        return { thread, conclusion, turns };
+    }
+    /** The entities a set of facts mentions — the key a conclusion is recalled by. */
+    entitiesOfFacts(factIds) {
+        const ids = new Set();
+        for (const factId of factIds) {
+            const fact = this.store.fact(factId);
+            for (const slot of fact?.slots ?? []) {
+                if (slot.value.kind === 'entity')
+                    ids.add(slot.value.entityId);
+            }
         }
+        return [...ids];
+    }
+    /**
+     * Conclusions worth comparing a new one against.
+     *
+     * Ordered by shared evidence first, then recency: two conclusions drawn from
+     * the same facts are the likeliest restatements, and the recency tail catches
+     * the ones whose evidence was reworded.
+     */
+    conclusionCandidates(evidence, limit = 8) {
+        const wanted = new Set(evidence);
+        const wantedEntities = new Set(this.entitiesOfFacts(evidence));
+        return this.conclusions(200)
+            .map((fact) => {
+            const ids = evidenceOf(fact);
+            const sharedEntities = fact.slots.filter((slot) => slot.slot === '关于' && slot.value.kind === 'entity' && wantedEntities.has(slot.value.entityId)).length;
+            // Shared evidence first, then the same person/thing: two conclusions about
+            // the same entity are the likeliest restatements even when their evidence
+            // happens to be disjoint.
+            const shared = ids.filter((id) => wanted.has(id)).length * 2 + sharedEntities;
+            return { fact, shared, evidence: ids.length };
+        })
+            .sort((a, b) => b.shared - a.shared)
+            .slice(0, limit)
+            .map((entry) => ({ id: entry.fact.id, statement: entry.fact.statement, evidence: entry.evidence }));
+    }
+    /**
+     * Fold new evidence into a held conclusion.
+     *
+     * The statement is not rewritten: keeping it makes the merge auditable, and a
+     * richer statement is the model's job at the next natural revision, not this
+     * function's.
+     */
+    mergeEvidence(into, evidence) {
+        const target = this.store.fact(into);
+        if (!target)
+            return { ok: false, reason: 'target-missing' };
+        if (target.typeName !== '结论')
+            return { ok: false, reason: 'target-not-conclusion' };
+        if (!isActive(target))
+            return { ok: false, reason: 'target-superseded' };
+        const held = evidenceOf(target);
+        const heldSet = new Set(held);
+        const added = this.store.addSlots(into, conclusionSlots(evidence.filter((id) => !heldSet.has(id)), this.entitiesOfFacts(evidence)));
+        // Confidence follows evidence count, as the gate does; never lower it.
+        const total = new Set([...held, ...evidence]).size;
+        const confidence = total >= 5 ? 0.85 : total >= 3 ? 0.7 : target.confidence;
+        this.store.setFactConfidence(into, Math.max(target.confidence, confidence));
+        return { ok: true, added };
+    }
+    /** Current conclusions, newest first. Superseded ones are history, not state. */
+    conclusions(limit = 20) {
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, holder: 'self', limit: 200 })
+            .filter((fact) => roleOf(fact) === 'judgment' && isActive(fact))
+            .slice(0, limit);
+    }
+    /**
+     * The newest facts, newest first — the input batch for consolidation.
+     *
+     * Observations only: conclusions share the same table, and feeding a conclusion
+     * back as evidence would let the model cite its own guess.
+     */
+    recentFacts(limit = 8) {
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: limit + 20 })
+            .filter((fact) => fact.typeName !== '结论')
+            .slice(0, limit);
+    }
+    /** How many observations exist; consolidation triggers on growth, not time. */
+    factTotal() {
+        return this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 100_000 })
+            .filter((fact) => fact.typeName !== '结论').length;
+    }
+    /**
+     * Everything that happened to or around one entity — the "about her" path.
+     *
+     * `order: 'asc'` gives the earliest fact, which is how "when we first met"
+     * is answered without storing a special label: the model reads the timeline.
+     */
+    factsAbout(entityId, options = {}) {
+        return this.store.facts({
+            soulId: this.soulId,
+            userId: this.userId,
+            entityId,
+            since: options.since,
+            until: options.until,
+            order: options.order,
+            limit: options.limit,
+        });
+    }
+    /** A fact plus the conversation behind it: hook first, detail on demand. */
+    factDetail(factId) {
+        const fact = this.store.fact(factId);
+        if (!fact)
+            return null;
+        const turn = fact.sourceTurnId ? this.store.turn(fact.sourceTurnId) : null;
+        return {
+            fact,
+            turn: turn
+                ? { id: turn.id, userText: turn.userText, assistantText: turn.assistantText, at: turn.at }
+                : undefined,
+        };
+    }
+    /** Open questions, highest tension first. */
+    openGaps(limit = 20) {
+        return this.store.openGaps(this.soulId, this.userId, limit);
+    }
+    recordGap(spec) {
+        return this.store.putGap({ ...spec, soulId: this.soulId, userId: this.userId });
+    }
+    closeGap(id, closedByFactId) {
+        this.store.closeGap(id, closedByFactId);
+    }
+    findTurns(text, options = {}) {
+        return this.store.findTurns({
+            soulId: this.soulId,
+            userId: this.userId,
+            text,
+            sessionId: options.sessionId,
+            since: options.since,
+            until: options.until,
+            limit: options.limit,
+        });
+    }
+    /** Conversations, most recent first, derived from the recorded exchanges. */
+    sessions(limit = 5) {
+        return this.store.listSessions(this.soulId, this.userId, limit);
+    }
+    /**
+     * What a new session inherits from the previous conversation.
+     *
+     * Measured: naive first/last picked "ok" and "停" — boundaries are not the
+     * same as signals. So the topic is the longest user message of that session
+     * (shortest messages carry no topic), and the tail is the last few exchanges
+     * whose user message has substance.
+     */
+    handoff(currentSessionId, tail = 2) {
+        const sessions = this.store.listSessions(this.soulId, this.userId, 20);
+        const previous = sessions.find((s) => s.sessionId !== currentSessionId);
+        if (!previous)
+            return null;
+        const pairs = this.store.sessionPairs(previous.sessionId, this.soulId, this.userId, 500);
+        if (pairs.length === 0)
+            return null;
+        const SUBSTANTIVE = 4;
+        const substantial = pairs.filter((p) => p.userText.trim().length >= SUBSTANTIVE);
+        const topic = [...substantial].sort((a, b) => b.userText.length - a.userText.length)[0] ?? pairs[0];
+        const last = (substantial.length > 0 ? substantial : pairs).slice(-tail);
+        return { session: previous, first: topic, last };
+    }
+    /**
+     * Verb 3: on demand.
+     *
+     * Reads facts, not the legacy `memories` table: after the migration that table is
+     * inert, and a recall that still read it would stay empty forever.
+     */
+    recall(query, limit = 5) {
+        const facts = this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 500 })
+            .filter((fact) => isActive(fact));
+        const ranked = rank(facts.map(factAsMemory), query, Date.now()).slice(0, limit);
+        return ranked;
+    }
+    /** Pure analysis, no storage. Async because the analyzer may call a model. */
+    async analyze(text) {
+        return this.analyzeTurn(text);
+    }
+    /**
+     * Verb 2: after each turn. Affect and emotion only.
+     *
+     * Memory writing moved to `extract()` + `commitDrafts()` (facts), which is the one
+     * representation the rest of the system reads. This method used to run a second
+     * model pass (`llmExtractTurn`) behind a second gate (`gateDrafts`) into the legacy
+     * `memories` table — two prompts, two gates, two model calls for the same message.
+     */
+    async observe(turn) {
+        const now = turn.at ?? Date.now();
+        const affect = turn.role === 'user' ? await this.analyzeTurn(turn.content) : emptyAffect();
         if (turn.role === 'user') {
             try {
                 this.store.saveAffect(this.soulId, this.userId, affect, now, this.deviceId);
@@ -231,72 +1041,68 @@ export class Soul {
         const emotion = nextEmotion(this.store.emotion(this.soulId, this.userId), [turn]);
         this.store.saveEmotion(this.soulId, this.userId, emotion, now);
         return {
-            written,
-            committed: written > 0,
-            rejections: gated.rejected,
-            llmOutcome,
+            written: 0,
+            committed: false,
+            rejections: [],
+            llmOutcome: 'off',
             emotion,
             affect,
-            extractedBy: written > 0 ? extractedBy : 'none',
+            extractedBy: 'none',
         };
     }
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.
-     * Same write path, no extraction heuristics.
+     *
+     * Writes a fact, like every other write path. This used to be a row in the legacy
+     * `memories` table, which meant "remember this" produced something the rest of the
+     * system (anchors, recall, conclusions) had to be told about separately.
      */
     remember(content, options = {}) {
-        const now = Date.now();
-        const id = `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-        this.store.put({
-            id,
-            soulId: this.soulId,
-            userId: this.userId,
-            type: options.type ?? 'fact',
-            content,
-            importance: options.importance ?? 6,
-            vividness: 0.9,
-            recallCount: 0,
-            status: 'active',
-            visibility: options.visibility ?? 'private',
-            keywords: tokenize(content),
-            createdAt: now,
-            updatedAt: now,
-            validFrom: now,
+        const fact = this.recordFact({
+            statement: content,
+            typeName: MEMORY_TYPE_TO_FACT[options.type ?? 'fact'],
+            holder: 'self',
+            source: 'told',
+            confidence: Math.min(1, Math.max(0, (options.importance ?? 6) / 10)),
+            // Explicit writes are anchors by definition: the host asked for this to be kept.
+            slots: [{ slot: '锚点', value: { kind: 'text', value: '是' } }],
         });
-        return id;
+        return fact.id;
     }
     /**
-     * Explicit write requested by a host or its model (RFC 0005). Unlike
-     * `remember`, it passes the same gates as `observe` and dedupes by content,
-     * so a tool cannot bypass shape/semantics or flood duplicates.
+     * Explicit write requested by a host or its model (RFC 0005).
+     *
+     * Writes a fact and keeps the old dedupe contract: exact duplicate returns the
+     * existing id, and a paraphrase inside the dedupe window is treated as the same
+     * statement. Shape checks are the statement checks (non-empty, short enough);
+     * the old `gateDrafts` layer existed only to protect the retired table.
      */
     rememberExplicit(input) {
         const type = input.type ?? 'fact';
         const importance = Math.min(10, Math.max(1, input.importance ?? 7));
-        const { accepted, rejected } = gateDrafts([{ type, content: input.content, importance }]);
-        if (accepted.length === 0) {
-            return { ok: false, reason: rejected[0]?.reason ?? 'rejected by write gates' };
-        }
-        const content = accepted[0].content;
+        const content = String(input.content ?? '').trim();
+        if (content.length < 2)
+            return { ok: false, reason: `length ${content.length} (2..${MAX_FACT_CHARS})` };
+        if (content.length > MAX_FACT_CHARS)
+            return { ok: false, reason: `length ${content.length} (2..${MAX_FACT_CHARS})` };
+        // Punctuation alone is not a statement; the old shape gate rejected it and that
+        // rule is worth keeping even though its table is gone.
+        if (!/[\p{L}\p{N}]/u.test(content))
+            return { ok: false, reason: 'no letters or digits' };
         const now = Date.now();
-        const candidates = this.store.query({
-            soulId: this.soulId,
-            userId: this.userId,
-            status: ['active'],
-            includeExpired: true,
-            limit: 50,
-        });
+        const candidates = this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 200 })
+            .filter((fact) => isActive(fact));
         // Same content anywhere: the exact duplicate.
-        const same = candidates.find((memory) => memory.content.trim() === content);
+        const same = candidates.find((fact) => fact.statement.trim() === content);
         if (same)
             return { ok: true, id: same.id, duplicate: true };
-        // A paraphrase of something just written (usually the automatic observer
-        // moments earlier) must not become a second row: a shared run of characters
-        // inside the dedupe window is treated as the same statement.
+        // A paraphrase of something just written must not become a second row: a shared
+        // run of characters inside the dedupe window is treated as the same statement.
         const window = this.dedupeWindowMs;
         if (window > 0) {
-            const recent = candidates.filter((memory) => now - memory.createdAt <= window);
-            const overlapping = recent.find((memory) => sharesRun(memory.content, content, MIN_SHARED_RUN));
+            const recent = candidates.filter((fact) => now - fact.createdAt <= window);
+            const overlapping = recent.find((fact) => sharesRun(fact.statement, content, MIN_SHARED_RUN));
             if (overlapping) {
                 return { ok: true, id: overlapping.id, duplicate: true, reason: 'already recorded this turn' };
             }
@@ -304,6 +1110,49 @@ export class Soul {
         const id = this.remember(content, { type, importance });
         return { ok: true, id };
     }
+    /**
+     * One-off: move the legacy `memories` rows into facts (ADR 0032), then retire them.
+     *
+     * The old rows are the only description of the soul's own lessons that exists, so
+     * they are copied — never rewritten — and marked superseded pointing at the new
+     * fact. Re-running is safe: a statement that already has a fact is linked, not
+     * copied again.
+     */
+    migrateLegacyMemories() {
+        const memories = this.store.query({ soulId: this.soulId, userId: this.userId, limit: 10_000 });
+        const existing = new Map(this.store
+            .facts({ soulId: this.soulId, userId: this.userId, limit: 10_000 })
+            .map((fact) => [fact.statement.trim(), fact]));
+        let migrated = 0;
+        let linked = 0;
+        let skipped = 0;
+        for (const memory of memories) {
+            if (memory.status !== 'active') {
+                skipped += 1;
+                continue;
+            }
+            const statement = memory.content.trim();
+            const known = existing.get(statement);
+            const fact = known ??
+                this.recordFact({
+                    statement,
+                    typeName: MEMORY_TYPE_TO_FACT[memory.type] ?? '事实',
+                    holder: 'self',
+                    source: 'told',
+                    confidence: Math.min(1, Math.max(0, memory.importance / 10)),
+                    // Migrated rows were explicit memories; keep them as anchors.
+                    slots: [{ slot: '锚点', value: { kind: 'text', value: '是' } }],
+                });
+            if (known)
+                linked += 1;
+            else {
+                existing.set(statement, fact);
+                migrated += 1;
+            }
+            this.store.retireMemory(memory.id, fact.id);
+        }
+        return { migrated, linked, skipped };
+    }
     /** Verb 4: session end. */
     async reflect(turns, options = {}) {
         return reflect(this.store, {
@@ -352,3 +1201,10 @@ function sharesRun(a, b, minRun) {
     }
     return false;
 }
+/** The fact ids a conclusion cites, in slot order. */
+function evidenceOf(fact) {
+    return fact.slots
+        .filter((slot) => slot.slot === '证据' && slot.value.kind === 'fact')
+        .map((slot) => (slot.value.kind === 'fact' ? slot.value.factId : ''))
+        .filter(Boolean);
+}