soulbridge 0.0.10 → 0.0.11

package/dist/packages/core/src/index.d.ts

@@ -56,7 +56,10 @@ export declare class Soul {
      * The analyzer may be async (a model); any failure degrades to the lexicon
      * analyzer. Emotion is computed from the turn only — never from affect.
      */
-    observe(turn: Turn): Promise<ObserveResult>;
+    observe(turn: Turn, options?: {
+        llm?: LlmFn;
+        maxLlmChars?: number;
+    }): Promise<ObserveResult>;
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.
      * Same write path, no extraction heuristics.

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

@@ -19,6 +19,7 @@ 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 { llmExtractTurn } from './reflect.js';
 export class Soul {
     store;
     soulId;
@@ -79,16 +80,38 @@ export class Soul {
      * The analyzer may be async (a model); any failure degrades to the lexicon
      * analyzer. Emotion is computed from the turn only — never from affect.
      */
-    async observe(turn) {
+    async observe(turn, options = {}) {
         const now = turn.at ?? Date.now();
         const affect = turn.role === 'user' ? await this.analyzeTurn(turn.content) : emptyAffect();
-        const drafts = ruleExtract([turn]);
+        // 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';
+        if (drafts.length === 0 && turn.role === 'user' && options.llm) {
+            const limit = options.maxLlmChars ?? 2000;
+            if (turn.content.length <= limit) {
+                try {
+                    const draft = await llmExtractTurn(turn.content, options.llm);
+                    if (draft) {
+                        drafts = [draft];
+                        extractedBy = 'llm';
+                    }
+                }
+                catch {
+                    // The model is an enhancement; a transport or parse failure leaves the
+                    // rule result (nothing) in place.
+                }
+            }
+        }
         // 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 drafts) {
             if (seen.has(draft.content.trim()))
                 continue;
             seen.add(draft.content.trim());
+            written += 1;
             this.store.put({
                 id: `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
                 soulId: this.soulId,
@@ -116,7 +139,7 @@ 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: drafts.length, emotion, affect };
+        return { written, emotion, affect, extractedBy: written > 0 ? extractedBy : 'none' };
     }
     /**
      * Explicit form of `observe`: the host decided this is worth keeping.

package/dist/packages/core/src/reflect.d.ts

@@ -44,4 +44,18 @@ export interface ReflectOptions {
     llm?: LlmFn;
 }
 export declare function reflect(store: SoulStore, options: ReflectOptions): Promise<ReflectResult>;
+/** Only these types travel over the port; episodic/relationship stay host-local. */
+export declare const LLM_MEMORY_TYPES: MemoryType[];
+export declare const LLM_PROMPT: string;
+export interface LlmDraft {
+    type: MemoryType;
+    content: string;
+    importance: number;
+}
+/**
+ * Ask the model for one memory. Returns null when the model deliberately says
+ * "nothing worth storing"; throws when the transport or the output is unusable,
+ * so the caller can fall back to rules.
+ */
+export declare function llmExtractTurn(text: string, llm: LlmFn): Promise<LlmDraft | null>;
 export {};

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

@@ -118,7 +118,26 @@ export function nextEmotion(current, turns) {
 }
 export async function reflect(store, options) {
     const now = options.now ?? Date.now();
-    const drafts = ruleExtract(options.turns);
+    const drafts = [];
+    if (options.llm) {
+        for (const turn of options.turns) {
+            if (turn.role !== 'user')
+                continue;
+            try {
+                const draft = await llmExtractTurn(turn.content, options.llm);
+                // A deliberate null means the model decided this is not worth storing.
+                if (draft)
+                    drafts.push(draft);
+            }
+            catch {
+                // Transport or parse failure: fall back to rules for this turn.
+                drafts.push(...ruleExtract([turn]));
+            }
+        }
+    }
+    else {
+        drafts.push(...ruleExtract(options.turns));
+    }
     const existing = store.query({ soulId: options.soulId, userId: options.userId });
     const seen = new Set(existing.map((m) => m.content));
     let written = 0;
@@ -151,3 +170,60 @@ export async function reflect(store, options) {
     }
     return { memories: written, superseded: 0, emotion };
 }
+/* ------------------------------------------------------------------ *
+ * LLM distillation port (optional)
+ *
+ * Core owns the prompt, the JSON contract and the fallback; adapters own the
+ * transport. A DSH adapter wraps `ctx.llm.stream`, a CLI adapter calls an
+ * OpenAI-compatible endpoint, and both satisfy the same `LlmFn`.
+ * ------------------------------------------------------------------ */
+/** Only these types travel over the port; episodic/relationship stay host-local. */
+export const LLM_MEMORY_TYPES = ['strategy', 'trait', 'fact', 'cognition'];
+export const LLM_PROMPT = [
+    '你是记忆提炼器。输入是用户的一段话，判断其中有没有值得长期记住的内容。',
+    '只输出 JSON，二选一：',
+    '{"type":"strategy|trait|fact|cognition|null","text":"不超过 40 字的记忆"}',
+    '规则：',
+    '1. 只保留长期有效的要求、偏好或事实；一次性的抱怨、讨论、玩笑都输出 null；',
+    '2. 保留条件（什么时候）和动作（做什么）；',
+    '3. 不要解释，不要编造原文没有的内容。',
+].join('\n');
+function parseLlmJson(raw) {
+    const trimmed = raw.trim().replace(/^```(?:json)?/i, '').replace(/```$/, '').trim();
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start < 0 || end < start)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(start, end + 1));
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask the model for one memory. Returns null when the model deliberately says
+ * "nothing worth storing"; throws when the transport or the output is unusable,
+ * so the caller can fall back to rules.
+ */
+export async function llmExtractTurn(text, llm) {
+    const raw = await llm(`${LLM_PROMPT}\n\n用户：${text}`);
+    const parsed = parseLlmJson(String(raw));
+    if (!parsed)
+        throw new Error('llm returned no JSON');
+    const type = parsed.type;
+    if (type === 'null' || parsed.text === undefined || parsed.text === null)
+        return null;
+    if (typeof type !== 'string' || !LLM_MEMORY_TYPES.includes(type)) {
+        throw new Error(`llm returned an unsupported type: ${String(type)}`);
+    }
+    const content = String(parsed.text).trim();
+    if (content.length === 0)
+        return null;
+    return {
+        type: type,
+        content: content.slice(0, 120),
+        importance: type === 'strategy' ? 7 : 6,
+    };
+}

package/dist/packages/core/src/types.d.ts

@@ -108,6 +108,8 @@ export interface ObserveResult {
     emotion: Emotion;
     /** Analysis of the user turn. Empty signal for assistant turns or on failure. */
     affect: AffectSignal;
+    /** Which extractor produced the memory, for measurement. */
+    extractedBy: 'rules' | 'llm' | 'none';
 }
 /** Injected by the caller. `core` never imports a model SDK. */
 export type LlmFn = (prompt: string) => Promise<string> | string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soulbridge",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",