@jbarket/loomai 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -12,6 +12,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-24
+
+### Changed
+
+- **The household, phase 2b: one directory entry per person, a relationship
+  per agent.** In a household a person card is kept in two places:
+  - **The directory** (`commons/people.db`): name, handles (`where`), and
+    the facts in `how` (`tz`, `timezone`, `pronouns`, `languages`), shared
+    by every agent.
+  - **Each agent's relationship** (its own `memories.db`): the summary, the
+    rest of `how` (how *this* agent talks to them) and `may`.
+
+  How it behaves:
+  - A read merges the two halves into one card, rendered exactly as before.
+  - A write splits by field. Both halves are rehearsed in memory first, so
+    a write either half would refuse changes neither.
+  - Revisions record the agent that made them (`person_revisions.actor`),
+    and `person_history` says which half each revision came from.
+  - "Memories newer than the card" counts each agent's own memories.
+
+  Moving in:
+  - `loom household commons` and `init` split an existing agent's cards,
+    checking first that every card still renders the same text. Running it
+    again is safe.
+  - A household daemon refuses to start with cards that haven't been split.
+- **The household, phase 2a: knowledge is the commons.**
+  - In a household, every agent reads and writes `commons/knowledge.db`.
+  - `loom household init` moves the first agent's knowledge there.
+  - `loom household commons` moves it for a household made before this
+    release. It checkpoints the WAL first, and must run with every daemon
+    stopped.
+  - A household daemon refuses to start while an agent still has its own
+    `knowledge.db`, so the knowledge base can't quietly fork.
+  - A plain context dir keeps its own knowledge, as before.
+
 ## [0.10.0] - 2026-10-24
 
 ### Security
@@ -697,7 +732,8 @@ Initial public release.
   stack and all added external-service dependencies or operational
   overhead.
 
-[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/sleepunit-agents/loom/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/sleepunit-agents/loom/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/sleepunit-agents/loom/compare/v0.9.2...v0.10.0
 [0.9.2]: https://github.com/sleepunit-agents/loom/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/sleepunit-agents/loom/compare/v0.9.0...v0.9.1

package/README.md

@@ -660,6 +660,7 @@ exactly as before.
 ```bash
 loom household init art             # ~/.config/loom/art → agents/art (a symlink stays)
 loom household add mark             # an agent whose dir already exists under agents/
+loom household commons              # once, daemons stopped: knowledge.db → commons/ (shared by every agent)
 loom token create --agent art --label "Art · house on wunder"   # printed once
 loom token create --owner --label "Jonathan · page"
 loom token list

package/dist/backends/migrations.js

@@ -337,6 +337,15 @@ export const MIGRATIONS = [
             }).immediate();
         },
     },
+    {
+        id: 'person_revisions_actor',
+        description: 'Add person_revisions.actor: which agent made the change a revision records, so a ' +
+            'shared directory entry shows who changed what (docs/specs/household.md)',
+        pending: (db) => hasTable(db, 'person_revisions') && !hasColumn(db, 'person_revisions', 'actor'),
+        run: (db) => {
+            db.prepare('ALTER TABLE person_revisions ADD COLUMN actor TEXT').run();
+        },
+    },
 ];
 /**
  * Apply pending migrations to a database.

package/dist/backends/people-household.d.ts

@@ -0,0 +1,77 @@
+import { PeopleStore, type MutationResult, type PersonCard, type PersonListEntry, type PersonReadResult, type PersonRevisionMeta, type PersonRow, type PersonWriteInput } from './people.js';
+import { type Household } from '../household.js';
+/** `how` fields that are facts about the person, not how one agent talks to them. */
+export declare const FACT_KEYS: ReadonlySet<string>;
+export declare function commonsPeoplePath(h: Household): string;
+/** The directory half and the relationship half of a whole card. */
+export declare function splitCard(card: PersonCard): {
+    directory: PersonCard;
+    relationship: PersonCard;
+};
+/** One card from its two halves. */
+export declare function mergeCard(d: PersonCard, r: PersonCard | null): PersonCard;
+export declare class HouseholdPeople {
+    private readonly directory;
+    private readonly relationship;
+    private readonly now;
+    constructor(directory: PeopleStore, relationship: PeopleStore, now?: () => number);
+    close(): void;
+    getRow(slug: string): PersonRow | null;
+    read(slug: string, includeArchived?: boolean): PersonReadResult;
+    list(includeArchived?: boolean): PersonListEntry[];
+    /**
+     * Split a write by field: name, `where` and the fact keys of `how` go to the
+     * directory; summary, the rest of `how` and `may` to this agent's
+     * relationship. Both halves are rehearsed against in-memory copies first,
+     * so a write either half would refuse changes neither.
+     */
+    write(input: PersonWriteInput): MutationResult;
+    verify(input: {
+        slug: string;
+        fields: string[];
+        verified_at?: string;
+        source?: string;
+    }): MutationResult;
+    archive(input: {
+        slug: string;
+        reason: string;
+        actor: string;
+    }): MutationResult;
+    restore(input: {
+        slug: string;
+    }): MutationResult;
+    /** Revisions from both halves, newest first, each saying which half and which agent. */
+    history(slug: string): PersonRevisionMeta[];
+    /**
+     * Restore one half to a revision: `store` says which (the relationship,
+     * unless named). A relationship revision from before the split holds the
+     * whole old card; only its relationship half comes back, so handles and
+     * facts never return to the agent's own store.
+     */
+    revisionRestore(input: {
+        slug: string;
+        revision_id: number;
+        store?: 'directory' | 'relationship';
+    }): MutationResult;
+    private mutation;
+}
+/**
+ * Open the people for a household agent: the commons directory plus the
+ * agent's relationships, both attributing revisions to the agent. A
+ * read-only open returns null when the directory doesn't exist yet.
+ */
+export declare function openHouseholdPeople(h: Household, agent: string, contextDir: string, opts?: {
+    readonly?: boolean;
+    now?: () => number;
+}): HouseholdPeople | null;
+/**
+ * Move an agent's whole cards into the household split: the directory half
+ * to the commons, the relationship half back in place (timestamps and
+ * archive state kept). Every card is checked first: merged back together it
+ * must render the same text it does today, or nothing is written. Refuses a
+ * slug the directory already has (merging a second agent's people is a later
+ * step). Returns how many cards moved.
+ */
+export declare function splitPeopleIntoCommons(h: Household, agent: string, contextDir: string, nowMs?: number): number;
+/** Whether an agent still holds directory fields (handles, facts) in its own cards: an unsplit store. */
+export declare function hasUnsplitPeople(contextDir: string): boolean;

package/dist/backends/people-household.js

@@ -0,0 +1,305 @@
+/**
+ * Person cards in a household (docs/specs/household.md, "The commons"): one
+ * card a reader sees, kept in two places.
+ *
+ *   directory     commons/people.db, one entry per human, shared by every
+ *                 agent: name, `where` (handles), and the facts in `how`
+ *                 that don't depend on who's asking (FACT_KEYS)
+ *   relationship  the agent's own memories.db: summary, the rest of `how`
+ *                 (how *this* agent talks to them), `may`
+ *
+ * A read merges the two into one card, rendered exactly as before. A write
+ * splits by field. Every revision names the agent that made it. No agent
+ * reads another's relationship: there's no API for it here.
+ *
+ * Same surface as PeopleStore, so the person tools don't care which they got.
+ */
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { PeopleStore, PersonCardError, renderCard, } from './people.js';
+import { resolveSqliteDbPath } from '../config.js';
+import { commonsDir } from '../household.js';
+/** `how` fields that are facts about the person, not how one agent talks to them. */
+export const FACT_KEYS = new Set(['tz', 'timezone', 'pronouns', 'languages']);
+export function commonsPeoplePath(h) {
+    return join(commonsDir(h), 'people.db');
+}
+function canonicalJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    if (v && typeof v === 'object')
+        return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(',')}}`;
+    return JSON.stringify(v);
+}
+function splitHow(how) {
+    const facts = {};
+    const rest = {};
+    for (const [k, v] of Object.entries(how ?? {}))
+        (FACT_KEYS.has(k) ? facts : rest)[k] = v;
+    return { facts, rest };
+}
+/** The directory half and the relationship half of a whole card. */
+export function splitCard(card) {
+    const { facts, rest } = splitHow(card.how);
+    return {
+        directory: { slug: card.slug, name: card.name, where: card.where ?? {}, how: facts, may: [] },
+        relationship: {
+            slug: card.slug, name: card.name, ...(card.summary !== undefined ? { summary: card.summary } : {}),
+            where: {}, how: rest, may: card.may ?? [],
+        },
+    };
+}
+/** One card from its two halves. */
+export function mergeCard(d, r) {
+    return {
+        slug: d.slug,
+        name: d.name,
+        ...(r?.summary !== undefined ? { summary: r.summary } : {}),
+        where: d.where ?? {},
+        how: { ...(r?.how ?? {}), ...(d.how ?? {}) },
+        may: r?.may ?? [],
+    };
+}
+/** Try a write against an in-memory copy of the current row; throws exactly what the real write would. */
+function rehearse(row, input, now) {
+    if (!input)
+        return;
+    const mem = new PeopleStore({ dbPath: ':memory:', now });
+    try {
+        if (row) {
+            mem.replaceCard(row.slug, row.card, {
+                updated: row.updated, synthesized_at: row.synthesized_at,
+                archived_at: row.archived_at, archived_by: row.archived_by, archive_reason: row.archive_reason,
+            });
+        }
+        mem.write(input);
+    }
+    finally {
+        mem.close();
+    }
+}
+export class HouseholdPeople {
+    directory;
+    relationship;
+    now;
+    constructor(directory, relationship, now = Date.now) {
+        this.directory = directory;
+        this.relationship = relationship;
+        this.now = now;
+    }
+    close() {
+        this.directory.close();
+        this.relationship.close();
+    }
+    getRow(slug) {
+        const d = this.directory.getRow(slug);
+        if (!d)
+            return null;
+        const r = this.relationship.getRow(slug);
+        return {
+            ...d,
+            card: mergeCard(d.card, r?.card ?? null),
+            updated: r && r.updated > d.updated ? r.updated : d.updated,
+            synthesized_at: r?.synthesized_at ?? null,
+        };
+    }
+    read(slug, includeArchived = false) {
+        const row = this.getRow(slug);
+        if (!row)
+            return this.directory.read(slug, includeArchived);
+        const archived = row.archived_at !== null;
+        if (archived && !includeArchived)
+            return { found: true, archived: true };
+        return {
+            found: true,
+            rendered: renderCard(row.card, this.now()) + (archived ? `\n_(archived ${row.archived_at} by ${row.archived_by}: ${row.archive_reason})_` : ''),
+            card: row.card,
+            archived,
+            updated: row.updated,
+            synthesized_at: row.synthesized_at,
+        };
+    }
+    list(includeArchived = false) {
+        const rel = new Map(this.relationship.list(true).map((e) => [e.slug, e]));
+        return this.directory.list(includeArchived).map((e) => {
+            const r = rel.get(e.slug);
+            const since = r?.synthesized_at ?? null;
+            return {
+                ...e,
+                updated: r && r.updated > e.updated ? r.updated : e.updated,
+                synthesized_at: since,
+                memories_since_synthesis: this.relationship.memoriesSince(e.slug, since),
+            };
+        });
+    }
+    /**
+     * Split a write by field: name, `where` and the fact keys of `how` go to the
+     * directory; summary, the rest of `how` and `may` to this agent's
+     * relationship. Both halves are rehearsed against in-memory copies first,
+     * so a write either half would refuse changes neither.
+     */
+    write(input) {
+        const merge = input.merge ?? true;
+        const dirRow = this.directory.getRow(input.slug);
+        const relRow = this.relationship.getRow(input.slug);
+        const name = input.name ?? dirRow?.card.name;
+        if (name === undefined)
+            throw new PersonCardError('name: is required to create a card');
+        const { facts, rest } = splitHow(input.how);
+        const dirInput = input.name !== undefined || input.where !== undefined || Object.keys(facts).length > 0 || !dirRow || !merge
+            ? { slug: input.slug, name, merge, ...(input.where !== undefined ? { where: input.where } : {}), how: facts }
+            : null;
+        const relInput = input.summary !== undefined || Object.keys(rest).length > 0 || input.may !== undefined || !merge || !relRow || (input.name !== undefined && relRow.card.name !== input.name)
+            ? {
+                slug: input.slug, name, merge,
+                ...(input.summary !== undefined ? { summary: input.summary } : {}),
+                how: rest,
+                ...(input.may !== undefined ? { may: input.may } : {}),
+            }
+            : null;
+        rehearse(dirRow, dirInput, this.now);
+        rehearse(relRow, relInput, this.now);
+        if (dirInput)
+            this.directory.write(dirInput);
+        if (relInput)
+            this.relationship.write(relInput);
+        return this.mutation(input.slug);
+    }
+    verify(input) {
+        this.directory.verify(input);
+        return this.mutation(input.slug);
+    }
+    archive(input) {
+        this.directory.archive(input);
+        if (this.relationship.getRow(input.slug))
+            this.relationship.archive(input);
+        return this.mutation(input.slug);
+    }
+    restore(input) {
+        this.directory.restore(input);
+        if (this.relationship.getRow(input.slug))
+            this.relationship.restore(input);
+        return this.mutation(input.slug);
+    }
+    /** Revisions from both halves, newest first, each saying which half and which agent. */
+    history(slug) {
+        return [
+            ...this.directory.history(slug).map((r) => ({ ...r, store: 'directory' })),
+            ...this.relationship.history(slug).map((r) => ({ ...r, store: 'relationship' })),
+        ].sort((a, b) => (a.replaced_at < b.replaced_at ? 1 : a.replaced_at > b.replaced_at ? -1 : 0));
+    }
+    /**
+     * Restore one half to a revision: `store` says which (the relationship,
+     * unless named). A relationship revision from before the split holds the
+     * whole old card; only its relationship half comes back, so handles and
+     * facts never return to the agent's own store.
+     */
+    revisionRestore(input) {
+        if (input.store === 'directory') {
+            this.directory.revisionRestore(input);
+            return this.mutation(input.slug);
+        }
+        const snap = this.relationship.revisionSnapshot(input.revision_id);
+        if (!snap)
+            throw new PersonCardError(`revision ${input.revision_id} not found`);
+        if (snap.slug !== input.slug)
+            throw new PersonCardError(`revision ${input.revision_id} belongs to another card, not ${input.slug}`);
+        if (!holdsDirectoryFields(snap.card)) {
+            this.relationship.revisionRestore(input);
+            return this.mutation(input.slug);
+        }
+        // The same gate the plain restore path has: no restoring onto an archived card.
+        const current = this.relationship.getRow(input.slug);
+        if (!current)
+            throw new PersonCardError(`no card for ${input.slug}`);
+        const dirRow = this.directory.getRow(input.slug);
+        if (!dirRow)
+            throw new PersonCardError(`no card for ${input.slug}`);
+        if (current.archived_at !== null || dirRow.archived_at !== null) {
+            throw new PersonCardError(`card for ${input.slug} is archived; person_restore it before restoring a revision`);
+        }
+        this.relationship.replaceCard(input.slug, splitCard(snap.card).relationship, {
+            updated: new Date(this.now()).toISOString(), synthesized_at: snap.synthesized_at ?? null,
+            archived_at: current.archived_at, archived_by: current.archived_by, archive_reason: current.archive_reason,
+        });
+        return this.mutation(input.slug);
+    }
+    mutation(slug) {
+        const row = this.getRow(slug);
+        if (!row)
+            throw new PersonCardError(`no card for ${slug}`);
+        return { card: row.card, unchanged: false, revision_id: null, archived: row.archived_at !== null, updated: row.updated, synthesized_at: row.synthesized_at };
+    }
+}
+/**
+ * Open the people for a household agent: the commons directory plus the
+ * agent's relationships, both attributing revisions to the agent. A
+ * read-only open returns null when the directory doesn't exist yet.
+ */
+export function openHouseholdPeople(h, agent, contextDir, opts = {}) {
+    const dirPath = commonsPeoplePath(h);
+    const relPath = resolveSqliteDbPath(contextDir);
+    if (opts.readonly && (!existsSync(dirPath) || !existsSync(relPath)))
+        return null;
+    if (!opts.readonly)
+        mkdirSync(commonsDir(h), { recursive: true, mode: 0o700 });
+    return new HouseholdPeople(new PeopleStore({ dbPath: dirPath, readonly: opts.readonly, now: opts.now, actor: agent }), new PeopleStore({ dbPath: relPath, readonly: opts.readonly, now: opts.now, actor: agent }), opts.now);
+}
+/**
+ * Move an agent's whole cards into the household split: the directory half
+ * to the commons, the relationship half back in place (timestamps and
+ * archive state kept). Every card is checked first: merged back together it
+ * must render the same text it does today, or nothing is written. Refuses a
+ * slug the directory already has (merging a second agent's people is a later
+ * step). Returns how many cards moved.
+ */
+export function splitPeopleIntoCommons(h, agent, contextDir, nowMs = Date.now()) {
+    if (!existsSync(resolveSqliteDbPath(contextDir)))
+        return 0;
+    mkdirSync(commonsDir(h), { recursive: true, mode: 0o700 });
+    const rel = new PeopleStore({ dbPath: resolveSqliteDbPath(contextDir), actor: agent });
+    const dir = new PeopleStore({ dbPath: commonsPeoplePath(h), actor: agent });
+    try {
+        const plan = rel.rows().flatMap((r) => {
+            const halves = splitCard(r.card);
+            const there = dir.getRow(r.slug);
+            // Already split (a re-run): the agent's card holds no handles or facts
+            // and the directory has the person.
+            if (there && !holdsDirectoryFields(r.card))
+                return [];
+            if (there && canonicalJson(there.card) !== canonicalJson(halves.directory)) {
+                throw new PersonCardError(`${r.slug} is already in the directory with different details; merging another agent's card into it isn't automatic yet`);
+            }
+            const before = renderCard(r.card, nowMs);
+            const after = renderCard(mergeCard(halves.directory, halves.relationship), nowMs);
+            if (before !== after)
+                throw new PersonCardError(`${r.slug} would render differently after the split; nothing was moved`);
+            return [{ r, halves }];
+        });
+        for (const { r, halves } of plan) {
+            const keep = { updated: r.updated, archived_at: r.archived_at, archived_by: r.archived_by, archive_reason: r.archive_reason };
+            dir.replaceCard(r.slug, halves.directory, { ...keep, synthesized_at: null });
+            rel.replaceCard(r.slug, halves.relationship, { ...keep, synthesized_at: r.synthesized_at });
+        }
+        return plan.length;
+    }
+    finally {
+        rel.close();
+        dir.close();
+    }
+}
+function holdsDirectoryFields(card) {
+    return Object.keys(card.where ?? {}).length > 0 || Object.keys(splitHow(card.how).facts).length > 0;
+}
+/** Whether an agent still holds directory fields (handles, facts) in its own cards: an unsplit store. */
+export function hasUnsplitPeople(contextDir) {
+    if (!existsSync(resolveSqliteDbPath(contextDir)))
+        return false;
+    const rel = new PeopleStore({ dbPath: resolveSqliteDbPath(contextDir), readonly: true });
+    try {
+        return rel.rows().some((r) => holdsDirectoryFields(r.card));
+    }
+    finally {
+        rel.close();
+    }
+}

package/dist/backends/people.d.ts

@@ -79,8 +79,12 @@ export interface PersonRevisionMeta {
     id: number;
     op: RevisionOp;
     replaced_at: string;
+    /** The agent whose change this revision records (null before households). */
+    actor?: string | null;
+    /** In a household: which half of the card this revision is from. */
+    store?: 'directory' | 'relationship';
 }
-export type RevisionOp = 'write' | 'verify' | 'archive' | 'restore' | 'revision_restore';
+export type RevisionOp = 'write' | 'verify' | 'archive' | 'restore' | 'revision_restore' | 'split';
 /** Every rejection the people surface makes. The message names the path. */
 export declare class PersonCardError extends Error {
     constructor(message: string);
@@ -112,6 +116,16 @@ export declare function fieldState(env: WhereEnvelope, nowMs: number): FieldStat
 export declare function renderCard(card: PersonCard, nowMs: number, opts?: {
     worstCase?: boolean;
 }): string;
+interface RawRow {
+    slug: string;
+    name: string;
+    card_json: string;
+    archived_at: string | null;
+    archived_by: string | null;
+    archive_reason: string | null;
+    updated: string;
+    synthesized_at: string | null;
+}
 export interface PeopleStoreConfig {
     dbPath: string;
     /** Open read-only and never migrate. Reads on an unmigrated store see no cards. */
@@ -119,6 +133,8 @@ export interface PeopleStoreConfig {
     busyTimeoutMs?: number;
     /** Clock, for tests. */
     now?: () => number;
+    /** Who is writing (an agent's name), recorded on every revision it makes. */
+    actor?: string;
 }
 /** Thrown when a stored row cannot be turned back into a card. */
 export declare class UnreadableCardError extends Error {
@@ -127,6 +143,7 @@ export declare class UnreadableCardError extends Error {
 export declare class PeopleStore {
     private db;
     private readonly now;
+    private readonly actor;
     /** False on a read-only store whose tables do not exist yet. */
     readonly migrated: boolean;
     constructor(config: PeopleStoreConfig);
@@ -163,6 +180,24 @@ export declare class PeopleStore {
     read(slug: string, includeArchived?: boolean): PersonReadResult;
     list(includeArchived?: boolean): PersonListEntry[];
     history(slug: string): PersonRevisionMeta[];
+    /**
+     * Put a card in place as is, keeping the row's timestamps and archive state
+     * (a migration, not an edit). Recorded as a 'split' revision when a row is
+     * replaced.
+     */
+    replaceCard(slug: string, card: PersonCard, keep: Pick<RawRow, 'updated' | 'synthesized_at' | 'archived_at' | 'archived_by' | 'archive_reason'>): void;
+    /** The raw stored rows (timestamps and archive state included), for a migration. */
+    rows(): Array<{
+        slug: string;
+        card: PersonCard;
+        updated: string;
+        synthesized_at: string | null;
+        archived_at: string | null;
+        archived_by: string | null;
+        archive_reason: string | null;
+    }>;
+    /** This database's `user` memories about a person, newer than `since` (all of them when null). */
+    memoriesSince(slug: string, since: string | null): number;
     /** A revision's snapshot (the whole previous row), for tests and inspection. */
     revisionSnapshot(id: number): {
         slug: string;
@@ -190,3 +225,4 @@ export interface RoomOptions {
  * block; one bad row gives that slug the unreadable line and the rest render.
  */
 export declare function roomBlock(contextDir: string, people: readonly string[] | undefined, opts?: RoomOptions): string | null;
+export {};

package/dist/backends/people.js

@@ -313,7 +313,7 @@ function canonical(v) {
     return JSON.stringify(v);
 }
 // ─── Store ───────────────────────────────────────────────────────────────────
-const PEOPLE_MIGRATION = 'people_cards';
+const PEOPLE_MIGRATIONS = ['people_cards', 'person_revisions_actor'];
 function hasTable(db, table) {
     return db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) !== undefined;
 }
@@ -339,19 +339,23 @@ function parseRow(raw) {
 export class PeopleStore {
     db;
     now;
+    actor;
     /** False on a read-only store whose tables do not exist yet. */
     migrated;
     constructor(config) {
         this.now = config.now ?? Date.now;
+        this.actor = config.actor ?? null;
         this.db = new BetterSqlite3(config.dbPath, config.readonly ? { readonly: true } : {});
         this.db.pragma(`busy_timeout = ${config.busyTimeoutMs ?? 5000}`);
         if (!config.readonly) {
             this.db.pragma('journal_mode = WAL');
             // Only this feature's migration: the people tables do not depend on the
             // memories schema, and a raw store must not half-run the others.
-            const m = MIGRATIONS.find((x) => x.id === PEOPLE_MIGRATION);
-            if (m.pending(this.db))
-                m.run(this.db);
+            for (const id of PEOPLE_MIGRATIONS) {
+                const m = MIGRATIONS.find((x) => x.id === id);
+                if (m.pending(this.db))
+                    m.run(this.db);
+            }
         }
         this.migrated = hasTable(this.db, 'people') && hasTable(this.db, 'person_revisions');
     }
@@ -368,8 +372,8 @@ export class PeopleStore {
         const snap = { ...prev, card: JSON.parse(prev.card_json) };
         delete snap.card_json;
         const id = Number(this.db
-            .prepare('INSERT INTO person_revisions (slug, snapshot_json, op, replaced_at) VALUES (?, ?, ?, ?)')
-            .run(prev.slug, JSON.stringify(snap), op, at).lastInsertRowid);
+            .prepare('INSERT INTO person_revisions (slug, snapshot_json, op, replaced_at, actor) VALUES (?, ?, ?, ?, ?)')
+            .run(prev.slug, JSON.stringify(snap), op, at, this.actor).lastInsertRowid);
         this.db
             .prepare(`DELETE FROM person_revisions WHERE slug = ? AND id NOT IN
            (SELECT id FROM person_revisions WHERE slug = ? ORDER BY id DESC LIMIT ?)`)
@@ -681,10 +685,41 @@ export class PeopleStore {
             fail(`slug: ${slugErr}`);
         if (!this.migrated)
             return [];
+        const hasActor = this.db.pragma('table_info(person_revisions)').some((c) => c.name === 'actor');
         return this.db
-            .prepare('SELECT id, op, replaced_at FROM person_revisions WHERE slug = ? ORDER BY id DESC')
+            .prepare(`SELECT id, op, replaced_at${hasActor ? ', actor' : ''} FROM person_revisions WHERE slug = ? ORDER BY id DESC`)
             .all(slug);
     }
+    /**
+     * Put a card in place as is, keeping the row's timestamps and archive state
+     * (a migration, not an edit). Recorded as a 'split' revision when a row is
+     * replaced.
+     */
+    replaceCard(slug, card, keep) {
+        validateCard(card, null);
+        this.mutate(() => {
+            const existing = this.readRow(slug);
+            if (existing)
+                this.snapshot(existing, 'split', this.nowIso());
+            this.store({ slug, name: card.name, card_json: JSON.stringify(card), ...keep });
+        });
+    }
+    /** The raw stored rows (timestamps and archive state included), for a migration. */
+    rows() {
+        if (!this.migrated)
+            return [];
+        return this.db.prepare('SELECT slug, name, card_json, archived_at, archived_by, archive_reason, updated, synthesized_at FROM people ORDER BY slug').all()
+            .map((r) => ({ slug: r.slug, card: JSON.parse(r.card_json), updated: r.updated, synthesized_at: r.synthesized_at, archived_at: r.archived_at, archived_by: r.archived_by, archive_reason: r.archive_reason }));
+    }
+    /** This database's `user` memories about a person, newer than `since` (all of them when null). */
+    memoriesSince(slug, since) {
+        if (!hasTable(this.db, 'memories'))
+            return 0;
+        const nowIso = new Date(this.now()).toISOString();
+        return this.db.prepare(`SELECT COUNT(*) AS n FROM memories
+       WHERE category = 'user' AND archived = 0 AND json_extract(metadata, '$.person') = ?
+         AND (expires_at IS NULL OR expires_at > ?) AND (? IS NULL OR created > ?)`).get(slug, nowIso, since, since).n;
+    }
     /** A revision's snapshot (the whole previous row), for tests and inspection. */
     revisionSnapshot(id) {
         const rev = this.db.prepare('SELECT snapshot_json FROM person_revisions WHERE id = ?').get(id);

package/dist/cli/household.js

@@ -3,7 +3,8 @@
  * neither is a remote verb, so they never run through /cli. They read and
  * write $LOOM_HOME (default ~/.config/loom) directly.
  */
-import { addAgent, createToken, householdHome, HouseholdError, initHousehold, loadHousehold, loadTokens, parseRole, revokeToken, } from '../household.js';
+import { addAgent, agentDir, moveKnowledgeToCommons, createToken, householdHome, HouseholdError, initHousehold, loadHousehold, loadTokens, parseRole, revokeToken, } from '../household.js';
+import { splitPeopleIntoCommons } from '../backends/people-household.js';
 const HOUSEHOLD_USAGE = `Usage: loom household <command>
 
   show                     The household at $LOOM_HOME: agents, the default, the owner
@@ -11,6 +12,10 @@ const HOUSEHOLD_USAGE = `Usage: loom household <command>
                            Make $LOOM_HOME/<agent> (a context dir) the first agent of a new
                            household: it moves to agents/<agent>, and a symlink stays behind
   add <agent>              Add an agent whose directory already exists under agents/
+  commons                  Move the default agent's knowledge.db to commons/knowledge.db and
+                           split every agent's person cards (handles and facts to the commons
+                           directory, the rest stays as its relationships). Once, with
+                           every loom daemon on this household stopped
 
 $LOOM_HOME defaults to ~/.config/loom.
 `;
@@ -52,7 +57,22 @@ export async function runHousehold(argv, io) {
                 return 2;
             }
             const h = initHousehold(householdHome(io.env), agent, { owner: flag(rest, '--owner') });
-            io.stdout(`Household at ${h.home}: ${agent} moved to agents/${agent}; ${h.home}/${agent} is now a symlink to it.\n`);
+            const cards = splitPeopleIntoCommons(h, agent, agentDir(h, agent));
+            io.stdout(`Household at ${h.home}: ${agent} moved to agents/${agent}; ${h.home}/${agent} is now a symlink to it. ${cards} person card${cards === 1 ? '' : 's'} split into the commons directory.\n`);
+            return 0;
+        }
+        if (sub === 'commons') {
+            const h = need(io);
+            if (!h)
+                return 1;
+            const moved = moveKnowledgeToCommons(h, h.default);
+            io.stdout(moved ? `Knowledge moved to ${moved}; every agent shares it now.\n` : `agents/${h.default} has no knowledge.db to move.\n`);
+            // Every agent's cards, so the daemon's "haven't been split" refusal can
+            // always be cleared here.
+            for (const a of h.agents) {
+                const cards = splitPeopleIntoCommons(h, a, agentDir(h, a));
+                io.stdout(`${a}: ${cards} person card${cards === 1 ? '' : 's'} split (handles and facts in the commons directory, the rest as ${a}'s relationships).\n`);
+            }
             return 0;
         }
         if (sub === 'add') {

package/dist/config.d.ts

@@ -24,6 +24,11 @@ export declare function assertContextBootable(contextDir: string, defaultPath?:
  */
 export declare function resolveRepoRoot(): string;
 export declare function resolveSqliteDbPath(contextDir: string): string;
+/**
+ * Knowledge is facts about the world. In a household it's the commons, shared
+ * by every agent (docs/specs/household.md); otherwise it lives in the
+ * agent's own context dir, as it always has.
+ */
 export declare function resolveKnowledgeDbPath(contextDir: string): string;
 /**
  * Resolve the acting identity's name for actor attribution (knowledge

package/dist/config.js

@@ -18,7 +18,7 @@ import { resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs';
-import { contextFromHome } from './household.js';
+import { commonsKnowledgePath, contextFromHome, householdOf } from './household.js';
 /**
  * The single canonical helper for the default context path. Every call
  * site that needs `~/.config/loom/default` must go through this —
@@ -72,8 +72,18 @@ export function resolveRepoRoot() {
 export function resolveSqliteDbPath(contextDir) {
     return process.env.LOOM_SQLITE_DB_PATH ?? resolve(contextDir, 'memories.db');
 }
+/**
+ * Knowledge is facts about the world. In a household it's the commons, shared
+ * by every agent (docs/specs/household.md); otherwise it lives in the
+ * agent's own context dir, as it always has.
+ */
 export function resolveKnowledgeDbPath(contextDir) {
-    return process.env.LOOM_KNOWLEDGE_DB_PATH ?? resolve(contextDir, 'knowledge.db');
+    if (process.env.LOOM_KNOWLEDGE_DB_PATH)
+        return process.env.LOOM_KNOWLEDGE_DB_PATH;
+    const hh = householdOf(contextDir);
+    if (hh)
+        return commonsKnowledgePath(hh.household);
+    return resolve(contextDir, 'knowledge.db');
 }
 /**
  * Resolve the acting identity's name for actor attribution (knowledge

package/dist/household.d.ts

@@ -99,3 +99,19 @@ export declare function addAgent(h: Household, agent: string): Household;
  * `<home>/agents/<name>` serves that household; see householdOf.)
  */
 export declare function contextFromHome(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function commonsDir(h: Household): string;
+/** The household's shared knowledge store. */
+export declare function commonsKnowledgePath(h: Household): string;
+/**
+ * Why this household can't serve yet, or null. An agent's own knowledge.db
+ * beside the commons would quietly fork the knowledge base, so both "only the
+ * agent's" (not moved yet) and "both" (needs a merge) are refusals.
+ */
+export declare function commonsProblem(h: Household): string | null;
+/**
+ * Move one agent's knowledge.db to the commons: checkpoint its WAL into the
+ * main file, then rename it (and any sidecars). Refuses when the commons
+ * already has a knowledge store. Run with every daemon on this household
+ * stopped.
+ */
+export declare function moveKnowledgeToCommons(h: Household, agent: string): string | null;

package/dist/household.js

@@ -16,6 +16,7 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import BetterSqlite3 from 'better-sqlite3';
 import { basename, dirname, join, resolve } from 'node:path';
 export const AGENT_NAME = /^[a-z][a-z0-9-]{0,39}$/;
 const HOUSEHOLD_FILE = 'household.json';
@@ -333,6 +334,21 @@ export function initHousehold(home, agent, opts = {}) {
     renameSync(from, to);
     symlinkSync(join('agents', agent), from);
     const h = { home, agents: [agent], default: agent, owner: opts.owner };
+    // The first agent's knowledge becomes the household's commons.
+    if (existsSync(join(to, 'knowledge.db')) && !existsSync(join(home, 'commons', 'knowledge.db'))) {
+        const kdb = new BetterSqlite3(join(to, 'knowledge.db'));
+        try {
+            kdb.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        finally {
+            kdb.close();
+        }
+        mkdirSync(join(home, 'commons'), { recursive: true, mode: 0o700 });
+        for (const ext of SQLITE_SIDECARS) {
+            if (existsSync(join(to, 'knowledge.db') + ext))
+                renameSync(join(to, 'knowledge.db') + ext, join(home, 'commons', 'knowledge.db') + ext);
+        }
+    }
     withLock(home, () => writePrivate(join(home, HOUSEHOLD_FILE), JSON.stringify({ v: 1, agents: h.agents, default: h.default, ...(h.owner ? { owner: h.owner } : {}) }, null, 2) + '\n'));
     return h;
 }
@@ -387,3 +403,57 @@ export function contextFromHome(env = process.env) {
         throw new HouseholdError(`LOOM_AGENT=${agent} isn't in the household at ${h.home} (${h.agents.join(', ')})`);
     return agentDir(h, agent);
 }
+// ─── The commons ─────────────────────────────────────────────────────────────
+export function commonsDir(h) {
+    return join(h.home, 'commons');
+}
+/** The household's shared knowledge store. */
+export function commonsKnowledgePath(h) {
+    return join(commonsDir(h), 'knowledge.db');
+}
+const SQLITE_SIDECARS = ['', '-wal', '-shm'];
+/**
+ * Why this household can't serve yet, or null. An agent's own knowledge.db
+ * beside the commons would quietly fork the knowledge base, so both "only the
+ * agent's" (not moved yet) and "both" (needs a merge) are refusals.
+ */
+export function commonsProblem(h) {
+    const commons = existsSync(commonsKnowledgePath(h));
+    for (const a of h.agents) {
+        if (!existsSync(join(agentDir(h, a), 'knowledge.db')))
+            continue;
+        return commons
+            ? `agents/${a}/knowledge.db exists beside commons/knowledge.db; merging an agent's knowledge into the commons isn't automatic yet, so move one aside`
+            : `agents/${a}/knowledge.db hasn't moved to the commons; with every loom daemon stopped, run: loom household commons`;
+    }
+    return null;
+}
+/**
+ * Move one agent's knowledge.db to the commons: checkpoint its WAL into the
+ * main file, then rename it (and any sidecars). Refuses when the commons
+ * already has a knowledge store. Run with every daemon on this household
+ * stopped.
+ */
+export function moveKnowledgeToCommons(h, agent) {
+    const from = join(agentDir(h, agent), 'knowledge.db');
+    if (!existsSync(from))
+        return null;
+    const to = commonsKnowledgePath(h);
+    if (existsSync(to))
+        throw new HouseholdError(`${to} already exists; merging another agent's knowledge into it isn't automatic yet`);
+    return withLock(h.home, () => {
+        const db = new BetterSqlite3(from);
+        try {
+            db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        finally {
+            db.close();
+        }
+        mkdirSync(commonsDir(h), { recursive: true, mode: 0o700 });
+        for (const ext of SQLITE_SIDECARS) {
+            if (existsSync(from + ext))
+                renameSync(from + ext, to + ext);
+        }
+        return to;
+    });
+}

package/dist/server.js

@@ -643,10 +643,12 @@ export function createLoomServer(config) {
         inputSchema: z.object({
             slug: slugParam,
             revision_id: z.number().int().positive().describe('Revision id from person_history.'),
+            store: z.enum(['directory', 'relationship']).optional().describe('In a household, which half the revision is from (person_history says): the shared directory ' +
+                'entry, or this agent\'s relationship (the default). Ignored outside a household.'),
         }).strict(),
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
-    }, async ({ slug, revision_id }) => {
-        const result = await personRevisionRestore(contextDir, { slug, revision_id });
+    }, async ({ slug, revision_id, store }) => {
+        const result = await personRevisionRestore(contextDir, { slug, revision_id, store });
         return { content: [{ type: 'text', text: result }] };
     });
     // MCP-App render probe — env-gated, throwaway. Not part of the tool surface

package/dist/tools/person.d.ts

@@ -16,6 +16,7 @@ export declare function personRestore(contextDir: string, input: {
 export declare function personRevisionRestore(contextDir: string, input: {
     slug: string;
     revision_id: number;
+    store?: 'directory' | 'relationship';
 }): Promise<string>;
 /** The `person` read. Throws on an invalid slug or an unreadable row; the MCP wrapper turns that into text. */
 export declare function readPerson(contextDir: string, slug: string, includeArchived?: boolean): PersonReadResult;

package/dist/tools/person.js

@@ -9,7 +9,9 @@
  * loom tool. The CLI (`loom person`) calls the read functions here too.
  */
 import { resolveIdentityName } from '../config.js';
-import { openPeopleStore, personSlugError, PersonCardError, UnreadableCardError, } from '../backends/people.js';
+import { householdOf } from '../household.js';
+import { openHouseholdPeople } from '../backends/people-household.js';
+import { openPeopleStore, PeopleStore, personSlugError, PersonCardError, UnreadableCardError, } from '../backends/people.js';
 const json = (v) => JSON.stringify(v, null, 2);
 /** Slugs validate before anything else, store or no store (criterion 11). */
 function assertSlug(slug) {
@@ -22,9 +24,20 @@ function errorText(e) {
         return `Error: ${e.message}`;
     return `Error: ${e.message ?? String(e)}`;
 }
+/**
+ * The people a context dir sees. In a household: the commons directory plus
+ * this agent's relationships (backends/people-household.ts). Otherwise the
+ * one store in the agent's memories.db, as before.
+ */
+function openPeople(contextDir, opts = {}) {
+    const hh = householdOf(contextDir);
+    if (hh)
+        return openHouseholdPeople(hh.household, hh.agent, contextDir, opts);
+    return openPeopleStore(contextDir, opts);
+}
 function withWritable(contextDir, fn) {
     try {
-        const store = openPeopleStore(contextDir);
+        const store = openPeople(contextDir);
         try {
             return json(fn(store));
         }
@@ -50,12 +63,12 @@ export async function personRestore(contextDir, input) {
     return withWritable(contextDir, (s) => s.restore(input));
 }
 export async function personRevisionRestore(contextDir, input) {
-    return withWritable(contextDir, (s) => s.revisionRestore(input));
+    return withWritable(contextDir, (s) => (s instanceof PeopleStore ? s.revisionRestore({ slug: input.slug, revision_id: input.revision_id }) : s.revisionRestore(input)));
 }
 /** The `person` read. Throws on an invalid slug or an unreadable row; the MCP wrapper turns that into text. */
 export function readPerson(contextDir, slug, includeArchived = false) {
     assertSlug(slug);
-    const store = openPeopleStore(contextDir, { readonly: true });
+    const store = openPeople(contextDir, { readonly: true });
     if (!store)
         return { found: false };
     try {
@@ -66,7 +79,7 @@ export function readPerson(contextDir, slug, includeArchived = false) {
     }
 }
 export function listPeople(contextDir, includeArchived = false) {
-    const store = openPeopleStore(contextDir, { readonly: true });
+    const store = openPeople(contextDir, { readonly: true });
     if (!store)
         return [];
     try {
@@ -95,7 +108,7 @@ export async function personList(contextDir, input) {
 export async function personHistory(contextDir, input) {
     try {
         assertSlug(input.slug);
-        const store = openPeopleStore(contextDir, { readonly: true });
+        const store = openPeople(contextDir, { readonly: true });
         if (!store)
             return json([]);
         try {

package/dist/transport/http-server.js

@@ -41,7 +41,8 @@ import { createBackend } from '../backends/index.js';
 import { handleCliBody } from './cli-endpoint.js';
 import { handleUi, isUiRequest, legacyUiAuth } from '../ui/handler.js';
 import { createKnowledgeOnlyServer } from './knowledge-server.js';
-import { agentDir, assertRealAgentDir, roleString, TokenResolver } from '../household.js';
+import { hasUnsplitPeople } from '../backends/people-household.js';
+import { agentDir, assertRealAgentDir, commonsProblem, roleString, TokenResolver } from '../household.js';
 import { createHash, timingSafeEqual as cryptoTimingSafeEqual } from 'node:crypto';
 import { assertSafeBind, checkBearer, checkBearerMulti, checkPayloadSize, DEFAULT_MAX_BODY_BYTES, } from './guards.js';
 /**
@@ -142,6 +143,14 @@ export async function startHttpServer(opts) {
         }
         for (const a of household.agents)
             assertRealAgentDir(household, a);
+        const problem = commonsProblem(household);
+        if (problem)
+            throw new Error(`startHttpServer: ${problem}`);
+        for (const a of household.agents) {
+            if (hasUnsplitPeople(agentDir(household, a))) {
+                throw new Error(`startHttpServer: agents/${a}'s person cards haven't been split into the commons; with every loom daemon stopped, run: loom household commons`);
+            }
+        }
     }
     const resolver = household ? new TokenResolver(household) : undefined;
     const ownerDigest = opts.token ? createHash('sha256').update(opts.token).digest() : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbarket/loomai",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "MCP server for persistent AI agent identity and memory. Single-file sqlite-vec + local ONNX embeddings; zero external services.",
   "type": "module",
   "main": "dist/index.js",