soulbridge 0.0.106 → 0.0.108

package/dist/packages/cli/src/cli.js

@@ -427,6 +427,28 @@ async function main() {
             out({ db: dbPath, ...soul.stats() });
             return;
         }
+        case 'person': {
+            // The reading side of the person layer: who they are, what happened recently, and the
+            // questions about them that are still open. No model call.
+            const name = positional[0];
+            if (!name)
+                throw new Error('usage: soulbridge person <name>');
+            const { soul } = open(flags);
+            const card = soul.personCard(name);
+            out({
+                entity: card.entity
+                    ? { id: card.entity.id, name: card.entity.name, type: card.entity.type, aliases: card.entity.aliases }
+                    : null,
+                recent: card.recent.map((fact) => ({
+                    at: fact.atText ?? (fact.at ? new Date(fact.at).toISOString().slice(0, 10) : undefined),
+                    role: fact.role,
+                    source: fact.source,
+                    statement: fact.statement,
+                })),
+                openGaps: card.openGaps.map((gap) => gap.topic),
+            });
+            return;
+        }
         case 'why': {
             // The reader for the 依据 slot: a fact I said must be traceable to the turn I said it
             // in, and a conclusion must be traceable to the facts that support it.
@@ -480,6 +502,7 @@ async function main() {
                 '  export --out <file>             导出 JSONL',
                 '  export --dir <directory>        导出可携带档案（archive/summary/injection）',
                 '  why <factId>                    这条事实的依据：来源轮次 / 证据',
+                '  person <name>                   某人的近况：最近事实 + 未闭合的问题',
                 '  import --in <file>              导入 JSONL',
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',

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

@@ -327,6 +327,17 @@ export declare class Soul {
         id: string;
         reason: 'archived' | 'quiet-turns' | 'quiet-time';
     }>;
+    /**
+     * Housekeeping that should run once per turn: close open questions nobody answered.
+     *
+     * A gap is only worth asking about while it is fresh; 14 days of silence means the moment
+     * passed. Closing is not deleting — the row keeps its topic, opened_at and the reason.
+     */
+    sweep(now?: number, options?: {
+        gapMaxAgeDays?: number;
+    }): {
+        gapsClosed: number;
+    };
     /** The thread the previous turn belonged to, for the attribution candidate list. */
     threadBefore(sessionId: string, turnNo: number): string | null;
     /**
@@ -411,6 +422,22 @@ export declare class Soul {
         limit?: number;
         order?: 'asc' | 'desc';
     }): Fact[];
+    /**
+     * What we know about one person right now: their record, the recent events, and the
+     * questions about them that are still open.
+     *
+     * This is the reading side of the person layer. It deliberately does not summarise with a
+     * model — the caller asks "how is she" and the model decides how to use these lines.
+     */
+    personCard(nameOrId: string, options?: {
+        limit?: number;
+    }): {
+        entity: Entity | null;
+        recent: Fact[];
+        openGaps: Gap[];
+    };
+    /** The open questions still attached to one person (the ones worth asking about). */
+    openGapsAbout(entityId: string): Gap[];
     /** A fact plus the conversation behind it: hook first, detail on demand. */
     factDetail(factId: string): FactDetail | null;
     /** Open questions, highest tension first. */

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

@@ -535,22 +535,10 @@ export class Soul {
                 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,
-                }));
-            }
+            // A missing date is a property of the fact (`atPrecision: unknown`), not an open
+            // question. Turning every undated fact into a gap produced 223 open gaps in two days,
+            // of which 78% were '日期不明：…' — they can never be closed, and they bury the gaps
+            // that are worth asking about. The fact stays; the question is not created.
             return written;
         };
         // Operations carry the merge decision (Mem0's ADD/UPDATE/DELETE); plain facts are
@@ -818,6 +806,17 @@ export class Soul {
     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());
     }
+    /**
+     * Housekeeping that should run once per turn: close open questions nobody answered.
+     *
+     * A gap is only worth asking about while it is fresh; 14 days of silence means the moment
+     * passed. Closing is not deleting — the row keeps its topic, opened_at and the reason.
+     */
+    sweep(now = Date.now(), options = {}) {
+        const maxAgeDays = options.gapMaxAgeDays ?? 14;
+        const gapsClosed = this.store.closeStaleGaps(this.soulId, this.userId, now - maxAgeDays * 86_400_000, 'expired');
+        return { gapsClosed };
+    }
     /** The thread the previous turn belonged to, for the attribution candidate list. */
     threadBefore(sessionId, turnNo) {
         return this.store.threadBefore(sessionId, turnNo);
@@ -961,6 +960,32 @@ export class Soul {
             limit: options.limit,
         });
     }
+    /**
+     * What we know about one person right now: their record, the recent events, and the
+     * questions about them that are still open.
+     *
+     * This is the reading side of the person layer. It deliberately does not summarise with a
+     * model — the caller asks "how is she" and the model decides how to use these lines.
+     */
+    personCard(nameOrId, options = {}) {
+        const entity = this.store.entity(nameOrId) ?? this.findEntities(nameOrId, 1)[0] ?? null;
+        if (!entity)
+            return { entity: null, recent: [], openGaps: [] };
+        const recent = this.store.facts({
+            soulId: this.soulId,
+            userId: this.userId,
+            entityId: entity.id,
+            limit: options.limit ?? 8,
+        });
+        const openGaps = this.openGapsAbout(entity.id);
+        return { entity, recent, openGaps };
+    }
+    /** The open questions still attached to one person (the ones worth asking about). */
+    openGapsAbout(entityId) {
+        return this.store
+            .openGaps(this.soulId, this.userId, 500)
+            .filter((gap) => gap.aboutEntityId === entityId);
+    }
     /** A fact plus the conversation behind it: hook first, detail on demand. */
     factDetail(factId) {
         const fact = this.store.fact(factId);

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

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { SoulStore } from './store.ts';
-export declare const SCHEMA_VERSION = 11;
+export declare const SCHEMA_VERSION = 13;
 export declare const AFFECT_RETENTION_MS: number;
 export declare class DbNewerThanBinaryError extends Error {
     readonly code = "DB_NEWER_THAN_BINARY";
@@ -13,6 +13,8 @@ export declare class DbNewerThanBinaryError extends Error {
  * old table stays as a read-only legacy copy.
  */
 /** v6 → v7: turn threads (a topic's turns need not be adjacent) plus turns.thread_id. */
+export declare function upgradeToV13(db: DatabaseSync): void;
+export declare function upgradeToV12(db: DatabaseSync): void;
 export declare function upgradeToV11(db: DatabaseSync): void;
 export declare function upgradeToV10(db: DatabaseSync): void;
 export declare function upgradeToV9(db: DatabaseSync): void;

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

@@ -12,7 +12,7 @@ import { DEFAULT_EMOTION } from './types.js';
 import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
 import { FACT_ROLES } from './config/domains.js';
 import { bm25, buildCorpusStats, tokenize } from './scoring.js';
-export const SCHEMA_VERSION = 11;
+export const SCHEMA_VERSION = 13;
 /** How many recent pairs are considered before scoring. Bounded so recall stays O(candidates). */
 const RECALL_CANDIDATES = 500;
 export const AFFECT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
@@ -174,6 +174,8 @@ CREATE TABLE IF NOT EXISTS facts (
   at_text        TEXT,
   at_end         INTEGER,
   at_precision   TEXT NOT NULL DEFAULT 'unknown',
+  valid_from     INTEGER,
+  valid_until    INTEGER,
   place_id       TEXT,
   status         TEXT NOT NULL DEFAULT 'active',
   confidence     REAL NOT NULL DEFAULT 1,
@@ -212,7 +214,8 @@ CREATE TABLE IF NOT EXISTS gaps (
   status            TEXT NOT NULL DEFAULT 'open',
   opened_at         INTEGER NOT NULL,
   closed_at         INTEGER,
-  closed_by_fact_id TEXT
+  closed_by_fact_id TEXT,
+  close_reason      TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_gaps_open ON gaps(soul_id, user_id, status, tension DESC);
 
@@ -299,6 +302,31 @@ function upgradeToV3(db) {
  * old table stays as a read-only legacy copy.
  */
 /** v6 → v7: turn threads (a topic's turns need not be adjacent) plus turns.thread_id. */
+export function upgradeToV13(db) {
+    // Two axes of time, like the legacy memory table had:
+    //   created_at   when we recorded it (never changes)
+    //   at           when the event happened (events only)
+    //   valid_from   when this claim became true
+    //   valid_until  when it stopped being true (NULL = still true)
+    // A state ("小林在 A 公司") ends when another fact replaces it; a historical event never
+    // stops being true, so its valid_until stays NULL.
+    ensureColumn(db, 'facts', 'valid_from', 'INTEGER');
+    ensureColumn(db, 'facts', 'valid_until', 'INTEGER');
+    db.exec("UPDATE facts SET valid_from = COALESCE(at, created_at) WHERE valid_from IS NULL");
+    // Retracted rows stopped holding when their successor was recorded (or when they were).
+    db.exec(`UPDATE facts SET valid_until = COALESCE(
+         (SELECT n.created_at FROM facts n WHERE n.id = facts.superseded_by),
+         created_at)
+      WHERE valid_until IS NULL AND status = 'retracted'`);
+}
+export function upgradeToV12(db) {
+    // A missing date is a property of the fact, not an open question. Existing gaps created by
+    // that old rule are closed with the reason, so the remaining open gaps are the ones that
+    // were worth asking about.
+    ensureColumn(db, 'gaps', 'close_reason', 'TEXT');
+    db.prepare(`UPDATE gaps SET status = 'closed', closed_at = ?, close_reason = 'time-unknown-not-a-gap'
+      WHERE status = 'open' AND topic LIKE '日期不明：%'`).run(Date.now());
+}
 export function upgradeToV11(db) {
     // 原则候选 stored a decision as a slot; it is role+status now. The row becomes a lesson
     // candidate — held and shown to the classifier, injected nowhere until it is placed.
@@ -463,8 +491,8 @@ export function openSqlite(file) {
                 upgradeToV7(db);
             if (version < 8)
                 upgradeToV8(db);
-            if (version < 11)
-                upgradeToV11(db);
+            if (version < 13)
+                upgradeToV13(db);
             // v6 adds tables only; SCHEMA creates them on every open, nothing to copy.
             setVersion(db, SCHEMA_VERSION);
             db.exec('COMMIT');
@@ -834,9 +862,10 @@ export function openSqlite(file) {
                 const inserted = db
                     .prepare(`INSERT OR IGNORE INTO facts
                (id, soul_id, user_id, statement, type_name, role, holder, at, at_text, at_end, at_precision,
-                place_id, status, confidence, source, source_turn_id, superseded_by, created_at)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(id, spec.soulId, spec.userId, spec.statement, spec.typeName ?? null, role, spec.holder ?? 'world', spec.at ?? null, spec.atText ?? null, spec.atEnd ?? null, spec.atPrecision ?? 'unknown', spec.placeId ?? null, spec.status ?? 'active', spec.confidence ?? 1, spec.source ?? 'experienced', spec.sourceTurnId ?? null, spec.supersededBy ?? null, createdAt);
+                valid_from, valid_until, place_id, status, confidence, source, source_turn_id, superseded_by,
+                created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(id, spec.soulId, spec.userId, spec.statement, spec.typeName ?? null, role, spec.holder ?? 'world', spec.at ?? null, spec.atText ?? null, spec.atEnd ?? null, spec.atPrecision ?? 'unknown', spec.validFrom ?? spec.at ?? createdAt, spec.validUntil ?? null, spec.placeId ?? null, spec.status ?? 'active', spec.confidence ?? 1, spec.source ?? 'experienced', spec.sourceTurnId ?? null, spec.supersededBy ?? null, createdAt);
                 if (Number(inserted.changes) > 0) {
                     const insertSlot = db.prepare(`INSERT INTO fact_slots (fact_id, slot, value_type, entity_id, value_num, value_text, ref_fact_id)
              VALUES (?, ?, ?, ?, ?, ?, ?)`);
@@ -889,9 +918,14 @@ export function openSqlite(file) {
             return rows.map((row) => rowToFact(row, slots));
         },
         supersedeFact(oldId, newId) {
+            // The old claim stopped holding when the new one was recorded. `valid_until` is the
+            // time axis; `status` is the lifecycle — both are written, and they answer different
+            // questions ("was it ever true?" vs "is it still the current state?").
+            const recordedAt = Number(db.prepare('SELECT created_at FROM facts WHERE id = ?').get(newId)?.created_at ??
+                Date.now());
             withRetry(() => db
-                .prepare(`UPDATE facts SET status = '${FACT_STATUS.retracted}', superseded_by = ? WHERE id = ?`)
-                .run(newId, oldId));
+                .prepare(`UPDATE facts SET status = '${FACT_STATUS.retracted}', superseded_by = ?, valid_until = ? WHERE id = ?`)
+                .run(newId, recordedAt, oldId));
         },
         /* ---------------- gaps ---------------- */
         putGap(spec) {
@@ -918,6 +952,17 @@ export function openSqlite(file) {
              WHERE id = ?`)
                 .run(at, closedByFactId ?? null, id));
         },
+        closeStaleGaps(soulId, userId, beforeAt, reason) {
+            let changed = 0;
+            withRetry(() => {
+                const result = db
+                    .prepare(`UPDATE gaps SET status = 'closed', closed_at = ?, close_reason = ?
+              WHERE soul_id = ? AND user_id = ? AND status = 'open' AND opened_at < ?`)
+                    .run(Date.now(), reason, soulId, userId, beforeAt);
+                changed = Number(result.changes);
+            });
+            return changed;
+        },
         turn(id) {
             const row = db.prepare('SELECT * FROM turns WHERE id = ?').get(id);
             return row ? rowToTurnPair(row) : null;
@@ -1362,6 +1407,8 @@ function rowToFact(row, slots) {
         atText: row.at_text === null ? undefined : String(row.at_text),
         atEnd: row.at_end === null ? undefined : Number(row.at_end),
         atPrecision: (row.at_precision ?? 'unknown'),
+        validFrom: row.valid_from == null ? undefined : Number(row.valid_from),
+        validUntil: row.valid_until == null ? undefined : Number(row.valid_until),
         placeId: row.place_id === null ? undefined : String(row.place_id),
         status: String(row.status),
         confidence: Number(row.confidence),

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

@@ -103,6 +103,11 @@ export interface SoulStore {
     putGap(spec: GapSpec): Gap;
     openGaps(soulId: string, userId: string, limit?: number): Gap[];
     closeGap(id: string, closedByFactId?: string, at?: number): void;
+    /**
+     * Close every open gap older than `beforeAt`, recording why. Returns how many were closed.
+     * An open question that nobody answered in weeks is not a question any more.
+     */
+    closeStaleGaps(soulId: string, userId: string, beforeAt: number, reason: string): number;
     /** Corrections the user made, newest first — the objective signal for behaviour changes. */
     corrections(soulId: string, userId: string, limit?: number): Correction[];
     /** Everything a portable bundle needs, scoped to one soul/user. */

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

@@ -385,6 +385,10 @@ export interface Fact {
     atEnd?: number;
     /** Locatability, not precision: unknown is a value (ADR 0032). */
     atPrecision?: AtPrecision;
+    /** When this claim became true (defaults to `at` or the record time). */
+    validFrom?: number;
+    /** When it stopped being true; undefined means it still holds. */
+    validUntil?: number;
     placeId?: string;
     status: FactStatus;
     confidence: number;
@@ -411,6 +415,10 @@ export interface FactSpec {
     atText?: string;
     atEnd?: number;
     atPrecision?: AtPrecision;
+    /** When the claim became true; the writer defaults it to `at` or the record time. */
+    validFrom?: number;
+    /** When it stopped being true; omitted means it still holds. */
+    validUntil?: number;
     placeId?: string;
     status?: FactStatus;
     confidence?: number;

package/package.json

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