@jbarket/loomai 0.10.0 → 0.12.0

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/cli/index.js

@@ -34,6 +34,8 @@ Commands:
   pieces            List installed pieces (loom-<name> on PATH)
   household         The household: agents and the default (docs/specs/household.md)
   token             Mint, list and revoke the household's tokens
+  export            Write the whole household to one encrypted bundle
+  restore           Lay a bundle down in an empty LOOM_HOME, or --drill it
 
 Pieces: \`loom <name> ...\` runs an installed extension, loom-<name> on PATH
 (e.g. loom tasks list). Core commands always win. See docs/extensions.md.
@@ -208,6 +210,14 @@ async function dispatch(sub, rest, io) {
             const { runToken } = await import('./household.js');
             return runToken(rest, io);
         }
+        case 'export': {
+            const { runExport } = await import('./bundle.js');
+            return runExport(rest, io);
+        }
+        case 'restore': {
+            const { runRestore } = await import('./bundle.js');
+            return runRestore(rest, io);
+        }
         default:
             io.stderr(`Subcommand not implemented yet: ${sub}\n`);
             return 2;

package/dist/cli/subcommands.d.ts

@@ -3,5 +3,5 @@
  * (src/cli/index.ts) and the CLI-vs-MCP routing gate (src/index.ts) so
  * the set never drifts between entry points.
  */
-export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces', 'household', 'token'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces', 'household', 'token', 'export', 'restore'];
 export type Subcommand = typeof SUBCOMMANDS[number];

package/dist/cli/subcommands.js

@@ -7,5 +7,5 @@ export const SUBCOMMANDS = [
     'wake', 'recall', 'remember', 'forget', 'update',
     'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve',
     'inject', 'harness',
-    'install', 'doctor', 'migrate', 'pieces', 'household', 'token',
+    'install', 'doctor', 'migrate', 'pieces', 'household', 'token', 'export', 'restore',
 ];

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.12.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",