soulbridge 0.0.107 → 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

@@ -422,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

@@ -960,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 = 12;
+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,7 @@ 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;

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 = 12;
+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,
@@ -300,6 +302,23 @@ 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
@@ -472,8 +491,8 @@ export function openSqlite(file) {
                 upgradeToV7(db);
             if (version < 8)
                 upgradeToV8(db);
-            if (version < 12)
-                upgradeToV12(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');
@@ -843,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 (?, ?, ?, ?, ?, ?, ?)`);
@@ -898,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) {
@@ -1382,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/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.107",
+  "version": "0.0.108",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",