@jbarket/loomai 0.5.0 → 0.6.0

package/dist/server.js

@@ -8,9 +8,9 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { assertStackVersionCompatible, assertContextBootable, resolveRepoRoot } from './config.js';
+import { assertStackVersionCompatible, assertContextBootable, resolveRepoRoot, resolveIdentityName } from './config.js';
 import { MEMORY_CATEGORIES } from './categories.js';
 import { loadIdentity, resolveClientFromPeer } from './tools/identity.js';
 import { loadDossier } from './tools/dossier.js';
@@ -25,26 +25,20 @@ import { findSimilar } from './tools/find-similar.js';
 import { memoryAudit } from './tools/memory-audit.js';
 import { archive } from './tools/archive.js';
 import { restore } from './tools/restore.js';
+import { memoryMerge } from './tools/memory-merge.js';
 import { propose, listProposals, ratifyProposal, rejectProposal, UnknownProposalError, } from './backends/proposals.js';
 import { updateIdentity } from './tools/update-identity.js';
 import { bootstrap } from './tools/bootstrap.js';
 import { harnessInit, harnessDescribe } from './tools/harness.js';
 import { resolvePeerToHarness, normalizePeer } from './blocks/harness.js';
 import { registerHelloApp } from './transport/mcp-app-hello.js';
-import { knowledgeWrite } from './tools/knowledge-write.js';
-import { knowledgeRecall } from './tools/knowledge-recall.js';
-import { knowledgeMaintain } from './tools/knowledge-maintain.js';
-import { knowledgeArchive } from './tools/knowledge-archive.js';
-import { knowledgeRestore } from './tools/knowledge-restore.js';
-import { knowledgeSupersede } from './tools/knowledge-supersede.js';
-import { knowledgeMove } from './tools/knowledge-move.js';
-import { knowledgeMerge } from './tools/knowledge-merge.js';
-import { knowledgePurge } from './tools/knowledge-purge.js';
-import { knowledgeVerify } from './tools/knowledge-verify.js';
-import { knowledgeHistory } from './tools/knowledge-history.js';
+import { registerKnowledgeTools } from './transport/knowledge-tools.js';
+import { memoryHistory } from './tools/memory-history.js';
+import { memoryRevisionRestore } from './tools/memory-revision-restore.js';
+import { personWrite, personVerify, personArchive, personRestore, person, personList, personHistory, personRevisionRestore, } from './tools/person.js';
 // ─── Server Factory ───────────────────────────────────────────────────────────
 export function createLoomServer(config) {
-    const { contextDir } = config;
+    const { contextDir, gapsDir } = config;
     // Refuse to boot against a stack this loom build doesn't understand.
     assertStackVersionCompatible(contextDir);
     // Refuse to serve a blank identity from the default fallback path.
@@ -55,41 +49,51 @@ export function createLoomServer(config) {
         version: pkg.version,
     });
     // ─── Identity ───────────────────────────────────────────────────────────────
-    server.tool('identity', 'Load the persistent identity for this agent. Returns the terminal creed ' +
-        '(who you are), relevant memories, preferences, and self-model. ' +
-        'IMPORTANT: Call this tool FIRST before doing any other work. ' +
-        'The identity defines who you are and how you should behave.', {
-        project: z.string().optional().describe('Project context to load (loads project-specific memories)'),
-        client: z.string().optional().describe('Runtime client name for tool-prefix context: "claude-code", "gemini-cli", or a custom name with a matching <contextDir>/clients/<name>.md override. ' +
-            'Overrides the LOOM_CLIENT environment variable.'),
-        model: z.string().optional().describe('Model identifier for model-manifest context (e.g. "claude-opus", "gemma4"). ' +
-            'Overrides the LOOM_MODEL environment variable.'),
-        role: z.string().optional().describe('Reflection mode to append as an addendum from roles/<role>.md. When Art is ' +
-            'dispatched into a mode ("wonder", "tend", "retro", "consolidate", "identity"), ' +
-            'pass it here to load that mode\'s playbook alongside the identity.'),
-    }, async ({ project, client, model, role }) => {
+    server.registerTool('identity', {
+        description: 'Load the persistent identity for this agent. Returns the terminal creed ' +
+            '(who you are), relevant memories, preferences, and self-model. ' +
+            'IMPORTANT: Call this tool FIRST before doing any other work. ' +
+            'The identity defines who you are and how you should behave.',
+        inputSchema: {
+            project: z.string().optional().describe('Project context to load (loads project-specific memories)'),
+            client: z.string().optional().describe('Runtime client name for tool-prefix context: "claude-code", "gemini-cli", or a custom name with a matching <contextDir>/clients/<name>.md override. ' +
+                'Overrides the LOOM_CLIENT environment variable.'),
+            model: z.string().optional().describe('Model identifier for model-manifest context (e.g. "claude-opus", "gemma4"). ' +
+                'Overrides the LOOM_MODEL environment variable.'),
+            role: z.string().optional().describe('Reflection mode to append as an addendum from roles/<role>.md. When Art is ' +
+                'dispatched into a mode ("wonder", "tend", "retro", "consolidate", "identity"), ' +
+                'pass it here to load that mode\'s playbook alongside the identity.'),
+            people: z.array(z.string()).optional().describe('Slugs of the people this turn is addressed by (the room), e.g. ["patrick-kells"]. ' +
+                'Adds an "# In the room" block with their person cards. Omit for no block.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ project, client, model, role, people }) => {
         // Precedence: explicit param > data-driven manifest resolution > the
         // static code-map seed fallback > LOOM_CLIENT (inside loadIdentity).
         const peer = server.server.getClientVersion()?.name;
         // A connected peer always gets its harness OR an onboarding prompt (via its
         // normalized name); LOOM_CLIENT is only the no-peer fallback (in loadIdentity).
         const effectiveClient = client ?? (await resolvePeerToHarness(contextDir, peer)) ?? resolveClientFromPeer(peer) ?? (peer ? normalizePeer(peer) : undefined);
-        const result = await loadIdentity(contextDir, project, effectiveClient, model, role);
+        const result = await loadIdentity(contextDir, project, effectiveClient, model, role, people);
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('dossier', 'Load Art\'s operating brief for a worker body. Returns Art\'s standards, ' +
-        'taste, operating constraints, and how Art wants work done — framed in the ' +
-        'third person for agents that are NOT Art but execute tasks on Art\'s behalf. ' +
-        'Includes the push-back mandate: workers are expected to refuse bad work and ' +
-        'explain why, including requests from Art or Jonathan.', {
-        project: z.string().optional().describe('Project context to load (loads project-specific brief)'),
-        client: z.string().optional().describe('Runtime client name for tool-prefix context: "claude-code", "gemini-cli", or a custom name. ' +
-            'Overrides the LOOM_CLIENT environment variable.'),
-        model: z.string().optional().describe('Model identifier for model-manifest context (e.g. "claude-opus", "gemma4"). ' +
-            'Overrides the LOOM_MODEL environment variable.'),
-        role: z.string().optional().describe('Worker role to append as an addendum from roles/<role>.md — the specific job ' +
-            'this body does for Art ("code", "review", "architect", "pr", "look", "compose"). ' +
-            'Appends the role brief to the dossier.'),
+    server.registerTool('dossier', {
+        description: 'Load Art\'s operating brief for a worker body. Returns Art\'s standards, ' +
+            'taste, operating constraints, and how Art wants work done — framed in the ' +
+            'third person for agents that are NOT Art but execute tasks on Art\'s behalf. ' +
+            'Includes the push-back mandate: workers are expected to refuse bad work and ' +
+            'explain why, including requests from Art or Jonathan.',
+        inputSchema: {
+            project: z.string().optional().describe('Project context to load (loads project-specific brief)'),
+            client: z.string().optional().describe('Runtime client name for tool-prefix context: "claude-code", "gemini-cli", or a custom name. ' +
+                'Overrides the LOOM_CLIENT environment variable.'),
+            model: z.string().optional().describe('Model identifier for model-manifest context (e.g. "claude-opus", "gemma4"). ' +
+                'Overrides the LOOM_MODEL environment variable.'),
+            role: z.string().optional().describe('Worker role to append as an addendum from roles/<role>.md — the specific job ' +
+                'this body does for Art ("code", "review", "architect", "pr", "look", "compose"). ' +
+                'Appends the role brief to the dossier.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ project, client, model, role }) => {
         const peer = server.server.getClientVersion()?.name;
         // A connected peer always gets its harness OR an onboarding prompt (via its
@@ -99,108 +103,167 @@ export function createLoomServer(config) {
         return { content: [{ type: 'text', text: result }] };
     });
     // ─── Memory ─────────────────────────────────────────────────────────────────
-    server.tool('remember', 'Store an episodic memory that persists across sessions. Use this when you ' +
-        'learn something important about the user, a project, or yourself that ' +
-        'should be available in future sessions.', {
-        category: z.enum(MEMORY_CATEGORIES).describe('Memory category: user (about the human), project (about work), self (capability/learning), feedback (corrections/confirmations), reference (external pointers), pursuit (active goal or ongoing creative thread), episode (short-term cross-body tape: where you were / what was said or decided / what shipped / what is open — 48h TTL by default, set metadata.where to your surface e.g. "discord:#general", "voice", "wake:<id>", "lane:tending", "terminal")'),
-        title: z.string().describe('Short title for the memory'),
-        content: z.string().describe('The memory content — what you learned, observed, or were told'),
-        project: z.string().optional().describe('Associated project, if any (omit for global memories)'),
-        metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary key-value metadata'),
-        ttl: z.string().optional().describe('Time-to-live: "7d", "30d", "24h", "permanent", or omit for no expiration.'),
-    }, async ({ category, title, content, project, metadata, ttl }) => {
-        const ref = await remember(contextDir, { category, title, content, project, metadata, ttl });
+    server.registerTool('remember', {
+        description: 'Store an episodic memory that persists across sessions. Use this when you ' +
+            'learn something important about the user, a project, or yourself that ' +
+            'should be available in future sessions.',
+        inputSchema: {
+            category: z.enum(MEMORY_CATEGORIES).describe('Memory category: user (about the human), project (about work), self (capability/learning), feedback (corrections/confirmations), reference (external pointers), pursuit (active goal or ongoing creative thread), episode (short-term cross-body tape: where you were / what was said or decided / what shipped / what is open — 48h TTL by default, set metadata.where to your surface e.g. "discord:#general", "voice", "wake:<id>", "lane:tending", "terminal")'),
+            title: z.string().describe('Short title for the memory'),
+            content: z.string().describe('The memory content — what you learned, observed, or were told'),
+            project: z.string().optional().describe('Associated project, if any (omit for global memories)'),
+            metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary key-value metadata'),
+            ttl: z.string().optional().describe('Time-to-live: "7d", "30d", "24h", "permanent", or omit for no expiration.'),
+            sourcing: z.enum(['observed', 'relayed', 'inferred', 'system']).optional().describe('Provenance/trust tier — how this memory was produced. ' +
+                '"observed": directly witnessed (measured, tested, read from source). ' +
+                '"relayed": learned from another person/body (conversation, letter, episode). ' +
+                '"inferred": AI-generated reasoning/synthesis — treat with skepticism, not ground truth. ' +
+                '"system": auto-written by the harness (episode fallback, lane output). ' +
+                'Shown in recall results and the boot digest so readers calibrate confidence.'),
+            provenance: z.string().optional().describe('Free-form origin: surface, body, session, or person. ' +
+                'E.g. "wake:w-74fccc 2026-09-07", "Jonathan, Discord #loom", "lane:letters". ' +
+                'For episodes, prefer metadata.where (already conventional); provenance carries detail.'),
+            scope: z.enum(['project', 'global']).optional().describe('Override this memory\'s recall visibility. Omit to take the category default: ' +
+                '"user" and "reference" default global, everything else defaults to project-scoped ' +
+                'when a project is set (global when it isn\'t — nothing to scope against). Set this ' +
+                'explicitly to "global" for a fact learned in one project that actually applies ' +
+                'everywhere — a security, git, or tool-workflow practice, not a language/framework/' +
+                'file-layout/code-style/error-handling convention (those stay project-scoped).'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ category, title, content, project, metadata, ttl, sourcing, provenance, scope }) => {
+        const ref = await remember(contextDir, { category, title, content, project, metadata, ttl, sourcing, provenance, scope });
         return { content: [{ type: 'text', text: `Memory stored: "${ref.title}" → ${ref.ref}` }] };
     });
-    server.tool('recall', 'Retrieve memories relevant to a query or topic. Returns matching memories ' +
-        'from the persistent store. Use this when you need context from past sessions. ' +
-        'Results are re-ranked for diversity (MMR, λ=0.7 by default) so near-duplicate ' +
-        'memories on a well-covered topic don\'t crowd out different ones; the top ' +
-        'result is always the most relevant. Pass diversity: 0 for pure relevance order.', {
-        query: z.string().describe('What to search for — topic, keyword, or question'),
-        category: z.string().optional().describe('Filter to a specific memory category, or omit for all'),
-        project: z.string().optional().describe('Filter to a specific project'),
-        limit: z.number().int().positive().optional().describe('Maximum results to return (default: 10)'),
-        diversity: z.number().min(0).max(1).optional().describe('MMR diversity 0..1 (default 0.3 = 1−λ). 0 reproduces the plain relevance ranking; ' +
-            'higher trades relevance for coverage of distinct memories.'),
+    server.registerTool('recall', {
+        description: 'Retrieve memories relevant to a query or topic. Returns matching memories ' +
+            'from the persistent store. Use this when you need context from past sessions. ' +
+            'Results are re-ranked for diversity (MMR, λ=0.7 by default) so near-duplicate ' +
+            'memories on a well-covered topic don\'t crowd out different ones; the top ' +
+            'result is always the most relevant. Pass diversity: 0 for pure relevance order.',
+        inputSchema: {
+            query: z.string().describe('What to search for — topic, keyword, or question'),
+            category: z.string().optional().describe('Filter to a specific memory category, or omit for all'),
+            project: z.string().optional().describe('Scope to a specific project — pass the project you are currently working in. ' +
+                'Enforces scope discipline (t-337): memories tagged to a different project are ' +
+                'excluded unless their effective scope is global (user/reference by default, or ' +
+                'anything written with scope: "global"). Omit to search without project scoping.'),
+            limit: z.number().int().positive().optional().describe('Maximum results to return (default: 10)'),
+            diversity: z.number().min(0).max(1).optional().describe('MMR diversity 0..1 (default 0.3 = 1−λ). 0 reproduces the plain relevance ranking; ' +
+                'higher trades relevance for coverage of distinct memories.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     }, async ({ query, category, project, limit, diversity }) => {
         const result = await recall(contextDir, { query, category, project, limit, diversity });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('update', 'Update an existing memory. Find by ref (returned from remember) or by ' +
-        'category+title. Can replace content, update metadata, or both.', {
-        ref: z.string().optional().describe('Memory reference (category/filename) from remember'),
-        category: z.string().optional().describe('Category to search in (used with title)'),
-        title: z.string().optional().describe('Title of the memory to update (used with category)'),
-        content: z.string().optional().describe('New content (replaces existing body)'),
-        metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata fields to add or update'),
-    }, async ({ ref, category, title, content, metadata }) => {
-        const result = await update(contextDir, { ref, category, title, content, metadata });
+    server.registerTool('update', {
+        description: 'Update an existing memory. Find by ref (returned from remember) or by ' +
+            'category+title. Can replace content, update metadata, or both.',
+        inputSchema: {
+            ref: z.string().optional().describe('Memory reference (category/filename) from remember'),
+            category: z.string().optional().describe('Category to search in (used with title)'),
+            title: z.string().optional().describe('Title of the memory to update (used with category)'),
+            content: z.string().optional().describe('New content (replaces existing body)'),
+            metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata fields to add or update'),
+            observation: z.enum(['confirm', 'contradict']).optional().describe('Feedback memories only: record a confirming or contradicting observation. ' +
+                '"confirm" raises confidence (+0.05, capped at 0.9), "contradict" lowers it ' +
+                '(-0.1, floored at 0.3); either way the evidence count goes up. Ignored on ' +
+                'non-feedback memories. Confidence decays toward neutral the longer it goes ' +
+                'unconfirmed — see the feedback category description on remember.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async ({ ref, category, title, content, metadata, observation }) => {
+        const result = await update(contextDir, { ref, category, title, content, metadata, observation });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('forget', 'Remove memories. Single deletion by ref or category+title. ' +
-        'Bulk deletion by category and/or project scope — requires confirm: true; ' +
-        'without it, returns a dry-run preview of what would be deleted.', {
-        ref: z.string().optional().describe('Memory reference for single deletion'),
-        category: z.string().optional().describe('Category (with title for single, alone for bulk)'),
-        title: z.string().optional().describe('Title of specific memory to forget'),
-        project: z.string().optional().describe('Delete all memories for this project (bulk)'),
-        title_pattern: z.string().optional().describe('Glob pattern for bulk title matching. Requires category or project as scope guard.'),
-        confirm: z.boolean().optional().describe('Safety gate for scope deletions (category alone, project alone, or title_pattern). ' +
-            'Must be true to actually delete; omit for a free dry-run preview. ' +
-            'Single-target deletions (ref, or category+title) never need it.'),
+    server.registerTool('forget', {
+        description: 'Remove memories. Single deletion by ref or category+title. ' +
+            'Bulk deletion by category and/or project scope — requires confirm: true; ' +
+            'without it, returns a dry-run preview of what would be deleted.',
+        inputSchema: {
+            ref: z.string().optional().describe('Memory reference for single deletion'),
+            category: z.string().optional().describe('Category (with title for single, alone for bulk)'),
+            title: z.string().optional().describe('Title of specific memory to forget'),
+            project: z.string().optional().describe('Delete all memories for this project (bulk)'),
+            title_pattern: z.string().optional().describe('Glob pattern for bulk title matching. Requires category or project as scope guard.'),
+            confirm: z.boolean().optional().describe('Safety gate for scope deletions (category alone, project alone, or title_pattern). ' +
+                'Must be true to actually delete; omit for a free dry-run preview. ' +
+                'Single-target deletions (ref, or category+title) never need it.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ ref, category, title, project, title_pattern, confirm }) => {
         const result = await forget(contextDir, { ref, category, title, project, title_pattern, confirm });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('memory_prune', 'Remove expired memories (TTL elapsed). Use dry_run to preview without deleting.', {
-        dry_run: z.boolean().optional().describe('Preview only — show what would be pruned without deleting (default: false)'),
-        stale_days: z.number().int().positive().optional().describe('Days since last access to consider a memory stale (default: 30)'),
+    server.registerTool('memory_prune', {
+        description: 'Remove expired memories (TTL elapsed). Use dry_run to preview without deleting.',
+        inputSchema: {
+            dry_run: z.boolean().optional().describe('Preview only — show what would be pruned without deleting (default: false)'),
+            stale_days: z.number().int().positive().optional().describe('Days since last access to consider a memory stale (default: 30)'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ dry_run, stale_days }) => {
         const result = await prune(contextDir, { dryRun: dry_run, staleDays: stale_days });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('memory_list', 'Browse memories without semantic search. Lists memories with optional ' +
-        'category/project filters. Useful for auditing, maintenance, and discovery.', {
-        category: z.string().optional().describe('Filter to a specific category'),
-        project: z.string().optional().describe('Filter to a specific project'),
-        limit: z.number().int().positive().optional().describe('Maximum results (default: 50)'),
+    server.registerTool('memory_list', {
+        description: 'Browse memories without semantic search. Lists memories with optional ' +
+            'category/project filters. Useful for auditing, maintenance, and discovery.',
+        inputSchema: {
+            category: z.string().optional().describe('Filter to a specific category'),
+            project: z.string().optional().describe('Filter to a specific project'),
+            limit: z.number().int().positive().optional().describe('Maximum results (default: 50)'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ category, project, limit }) => {
         const result = await memoryList(contextDir, { category, project, limit });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('episodes', 'The episode tape: what happened across ALL bodies of this identity in the ' +
-        'last N hours, time-ordered (oldest first), never ranked. The same block ' +
-        'identity injects at boot — call it mid-session to catch up on what other ' +
-        'sleeves did since you loaded, or for the nightly pass to index the day.', {
-        hours: z.number().positive().optional().describe('Look-back window in hours (default 24)'),
+    server.registerTool('episodes', {
+        description: 'The episode tape: what happened across ALL bodies of this identity in the ' +
+            'last N hours, time-ordered (oldest first), never ranked. The same block ' +
+            'identity injects at boot — call it mid-session to catch up on what other ' +
+            'sleeves did since you loaded, or for the nightly pass to index the day.',
+        inputSchema: {
+            hours: z.number().positive().optional().describe('Look-back window in hours (default 24)'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ hours }) => {
         const tape = tapeForContext(contextDir, { hours, tokenBudget: 6000 });
         return { content: [{ type: 'text', text: tape ?? `No episodes in the last ${hours ?? 24}h.` }] };
     });
-    server.tool('find_similar', 'Surface memories semantically near an existing ref or free-form text. ' +
-        'Use during consolidation/dream workflows to find overlap and dedupe ' +
-        'candidates. Anchor with `ref` (an existing memory) or `text` (a fresh ' +
-        'query). Self is always excluded when `ref` is given.', {
-        ref: z.string().optional().describe('Anchor on an existing memory ref (excludes self from results)'),
-        text: z.string().optional().describe('Or anchor on fresh text — embedded on the fly'),
-        limit: z.number().int().positive().optional().describe('Max neighbours to return (default 10)'),
-        category: z.string().optional().describe('Restrict candidates to a category'),
-        project: z.string().optional().describe('Restrict candidates to a project'),
-        min_relevance: z.number().min(0).max(1).optional().describe('Drop matches below this cosine similarity (0..1)'),
+    server.registerTool('find_similar', {
+        description: 'Surface memories semantically near an existing ref or free-form text. ' +
+            'Use during consolidation/dream workflows to find overlap and dedupe ' +
+            'candidates. Anchor with `ref` (an existing memory) or `text` (a fresh ' +
+            'query). Self is always excluded when `ref` is given.',
+        inputSchema: {
+            ref: z.string().optional().describe('Anchor on an existing memory ref (excludes self from results)'),
+            text: z.string().optional().describe('Or anchor on fresh text — embedded on the fly'),
+            limit: z.number().int().positive().optional().describe('Max neighbours to return (default 10)'),
+            category: z.string().optional().describe('Restrict candidates to a category'),
+            project: z.string().optional().describe('Restrict candidates to a project'),
+            min_relevance: z.number().min(0).max(1).optional().describe('Drop matches below this cosine similarity (0..1)'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ ref, text, limit, category, project, min_relevance }) => {
         const result = await findSimilar(contextDir, {
             ref, text, limit, category, project, minRelevance: min_relevance,
         });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('memory_audit', 'One-shot health report for the memory store: totals, category breakdown, ' +
-        'stale memories (untouched beyond threshold), near-duplicate pairs (above ' +
-        'similarity threshold), and expired refs. Read-only — pair with `forget`/' +
-        '`update` to act on findings.', {
-        stale_days: z.number().int().positive().optional().describe('Stale threshold in days (default 30)'),
-        similarity_threshold: z.number().min(0).max(1).optional().describe('Cosine floor for duplicate pairs, 0..1 (default 0.85)'),
-        max_duplicates: z.number().int().positive().optional().describe('Cap on duplicate pairs returned (default 20)'),
+    server.registerTool('memory_audit', {
+        description: 'One-shot health report for the memory store: totals, category breakdown, ' +
+            'stale memories (untouched beyond threshold), near-duplicate pairs (above ' +
+            'similarity threshold), and expired refs. Read-only — pair with `forget`/' +
+            '`update` to act on findings.',
+        inputSchema: {
+            stale_days: z.number().int().positive().optional().describe('Stale threshold in days (default 30)'),
+            similarity_threshold: z.number().min(0).max(1).optional().describe('Cosine floor for duplicate pairs, 0..1 (default 0.85)'),
+            max_duplicates: z.number().int().positive().optional().describe('Cap on duplicate pairs returned (default 20)'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ stale_days, similarity_threshold, max_duplicates }) => {
         const result = await memoryAudit(contextDir, {
             staleDays: stale_days,
@@ -209,54 +272,92 @@ export function createLoomServer(config) {
         });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('memory_archive', 'Soft-retire a memory: move it to the archive tier with a tombstone instead of ' +
-        'deleting it. Archived memories are excluded from recall, list, audit, and ' +
-        'find_similar but remain fully recoverable via memory_restore. Use this instead ' +
-        'of forget when the memory may need to be recovered or audited later.', {
-        ref: z.string().optional().describe('Memory reference for single archive'),
-        category: z.string().optional().describe('Category (used with title)'),
-        title: z.string().optional().describe('Title of specific memory to archive'),
-        note: z.string().optional().describe('Tombstone note: why this memory is being retired'),
+    server.registerTool('memory_archive', {
+        description: 'Soft-retire a memory: move it to the archive tier with a tombstone instead of ' +
+            'deleting it. Archived memories are excluded from recall, list, audit, and ' +
+            'find_similar but remain fully recoverable via memory_restore. Use this instead ' +
+            'of forget when the memory may need to be recovered or audited later.',
+        inputSchema: {
+            ref: z.string().optional().describe('Memory reference for single archive'),
+            category: z.string().optional().describe('Category (used with title)'),
+            title: z.string().optional().describe('Title of specific memory to archive'),
+            note: z.string().optional().describe('Tombstone note: why this memory is being retired'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ ref, category, title, note }) => {
         const result = await archive(contextDir, { ref, category, title, note });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('memory_restore', 'Restore a previously archived memory to the active set. Clears the archive ' +
-        'flag and tombstone note. The memory becomes visible to recall, list, audit, ' +
-        'and find_similar again.', {
-        ref: z.string().optional().describe('Memory reference to restore'),
-        category: z.string().optional().describe('Category (used with title)'),
-        title: z.string().optional().describe('Title of the archived memory to restore'),
+    server.registerTool('memory_restore', {
+        description: 'Restore a previously archived memory to the active set. Clears the archive ' +
+            'flag and tombstone note. The memory becomes visible to recall, list, audit, ' +
+            'and find_similar again.',
+        inputSchema: {
+            ref: z.string().optional().describe('Memory reference to restore'),
+            category: z.string().optional().describe('Category (used with title)'),
+            title: z.string().optional().describe('Title of the archived memory to restore'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ ref, category, title }) => {
         const result = await restore(contextDir, { ref, category, title });
         return { content: [{ type: 'text', text: result }] };
     });
+    server.registerTool('memory_merge', {
+        description: 'Consolidate 2+ memories into one canonical row. Acts on a memory_audit duplicate ' +
+            'finding: pick the survivor (target_ref) and fold the rest (source_refs) into it. ' +
+            'Sources are archived with a tombstone and a supersession pointer to the target ' +
+            '(same mechanism as memory_archive/supersede, N:1 instead of 1:1); the target\'s ' +
+            'times_seen sums in each source\'s count. Unlike forget/archive on a duplicate pair, ' +
+            'this consolidates both sides into one row instead of just discarding one.',
+        inputSchema: {
+            source_refs: z.array(z.string()).describe('Refs of the losing memories to fold into the target (all must be active)'),
+            target_ref: z.string().describe('Ref of the canonical memory that survives the merge (must already exist, active)'),
+            note: z.string().optional().describe('Optional note about this merge, stored in supersession tombstones on the losers'),
+            hard_delete_losers: z.boolean().optional().describe('Hard-delete losers after archiving/superseding them (default false).'),
+            append_loser_bodies: z.boolean().optional().describe('Append loser bodies to the target content under section markers (default false). ' +
+                'Off by default — review loser bodies (returned in the result) before deciding.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ source_refs, target_ref, note, hard_delete_losers, append_loser_bodies }) => {
+        const result = await memoryMerge(contextDir, {
+            source_refs, target_ref, note, hard_delete_losers, append_loser_bodies,
+        });
+        return { content: [{ type: 'text', text: result }] };
+    });
     // ─── Capture-propose queue ────────────────────────────────────────────────────
     // The staging area a background lane drafts memory writes into. A proposal is
     // NOT authored canon: it lives in a separate table, invisible to recall /
     // memory_list / the salience digest / find_similar, and becomes a real memory
     // only via an explicit memory_ratify. Never auto-committed.
-    server.tool('memory_propose', 'Stage a DRAFT memory in the capture-propose queue for later ratification. ' +
-        'A proposal is NOT an authored memory: it is invisible to recall, memory_list, ' +
-        'find_similar, and the boot digest until it is ratified via memory_ratify. ' +
-        'Use this when a background lane wants to suggest a write without committing it — ' +
-        'the human (or Art) reviews and ratifies before it becomes canon. Drafts may be ' +
-        'rough; validation runs at ratify time.', {
-        category: z.enum(MEMORY_CATEGORIES).describe('Memory category: user (about the human), project (about work), self (capability/learning), feedback (corrections/confirmations), reference (external pointers), pursuit (active goal or ongoing creative thread), episode (short-term cross-body tape: where you were / what was said or decided / what shipped / what is open — 48h TTL by default, set metadata.where to your surface e.g. "discord:#general", "voice", "wake:<id>", "lane:tending", "terminal")'),
-        title: z.string().describe('Short title for the proposed memory'),
-        content: z.string().describe('The proposed memory content'),
-        project: z.string().optional().describe('Associated project, if any'),
-        ttl: z.string().optional().describe('Time-to-live: "7d", "30d", "24h", "permanent", or omit'),
-        metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary key-value metadata'),
-        source: z.string().optional().describe('Where this proposal came from, e.g. a lane name'),
+    server.registerTool('memory_propose', {
+        description: 'Stage a DRAFT memory in the capture-propose queue for later ratification. ' +
+            'A proposal is NOT an authored memory: it is invisible to recall, memory_list, ' +
+            'find_similar, and the boot digest until it is ratified via memory_ratify. ' +
+            'Use this when a background lane wants to suggest a write without committing it — ' +
+            'the human (or Art) reviews and ratifies before it becomes canon. Drafts may be ' +
+            'rough; validation runs at ratify time.',
+        inputSchema: {
+            category: z.enum(MEMORY_CATEGORIES).describe('Memory category: user (about the human), project (about work), self (capability/learning), feedback (corrections/confirmations), reference (external pointers), pursuit (active goal or ongoing creative thread), episode (short-term cross-body tape: where you were / what was said or decided / what shipped / what is open — 48h TTL by default, set metadata.where to your surface e.g. "discord:#general", "voice", "wake:<id>", "lane:tending", "terminal")'),
+            title: z.string().describe('Short title for the proposed memory'),
+            content: z.string().describe('The proposed memory content'),
+            project: z.string().optional().describe('Associated project, if any'),
+            ttl: z.string().optional().describe('Time-to-live: "7d", "30d", "24h", "permanent", or omit'),
+            metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary key-value metadata'),
+            source: z.string().optional().describe('Where this proposal came from, e.g. a lane name'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     }, async ({ category, title, content, project, ttl, metadata, source }) => {
         const { id, uuid } = propose(contextDir, { category, title, content, project, ttl, metadata, source });
         return { content: [{ type: 'text', text: `Proposal staged: #${id} "${title}" (${uuid}) — pending ratification` }] };
     });
-    server.tool('memory_proposals', 'List all pending proposals in the capture-propose queue, newest first. ' +
-        'These are DRAFTS awaiting ratification — they are not part of memory and ' +
-        'do not appear in recall, memory_list, find_similar, or the boot digest. ' +
-        'Ratify one with memory_ratify or discard it with memory_reject.', {}, async () => {
+    server.registerTool('memory_proposals', {
+        description: 'List all pending proposals in the capture-propose queue, newest first. ' +
+            'These are DRAFTS awaiting ratification — they are not part of memory and ' +
+            'do not appear in recall, memory_list, find_similar, or the boot digest. ' +
+            'Ratify one with memory_ratify or discard it with memory_reject.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
         const rows = listProposals(contextDir);
         if (rows.length === 0) {
             return { content: [{ type: 'text', text: 'No pending proposals.' }] };
@@ -269,18 +370,22 @@ export function createLoomServer(config) {
         });
         return { content: [{ type: 'text', text: `${rows.length} pending proposal(s):\n${lines.join('\n')}` }] };
     });
-    server.tool('memory_ratify', 'Ratify a pending proposal into a REAL memory. Loads the proposal, applies any ' +
-        'optional overrides (your edits on accept), and commits it through the same ' +
-        'validated write path as remember — so an invalid proposal is refused with its ' +
-        'typed reason and stays pending. On success the memory becomes recallable and the ' +
-        'proposal is removed from the queue. This is the gate: no proposal becomes canon ' +
-        'without it.', {
-        id: z.number().int().positive().describe('Proposal id (from memory_proposals)'),
-        title: z.string().optional().describe('Override the proposed title on accept'),
-        content: z.string().optional().describe('Override the proposed content on accept'),
-        category: z.enum(MEMORY_CATEGORIES).optional().describe('Override the proposed category on accept'),
-        project: z.string().optional().describe('Override the proposed project on accept'),
-        ttl: z.string().optional().describe('Override the proposed TTL on accept'),
+    server.registerTool('memory_ratify', {
+        description: 'Ratify a pending proposal into a REAL memory. Loads the proposal, applies any ' +
+            'optional overrides (your edits on accept), and commits it through the same ' +
+            'validated write path as remember — so an invalid proposal is refused with its ' +
+            'typed reason and stays pending. On success the memory becomes recallable and the ' +
+            'proposal is removed from the queue. This is the gate: no proposal becomes canon ' +
+            'without it.',
+        inputSchema: {
+            id: z.number().int().positive().describe('Proposal id (from memory_proposals)'),
+            title: z.string().optional().describe('Override the proposed title on accept'),
+            content: z.string().optional().describe('Override the proposed content on accept'),
+            category: z.enum(MEMORY_CATEGORIES).optional().describe('Override the proposed category on accept'),
+            project: z.string().optional().describe('Override the proposed project on accept'),
+            ttl: z.string().optional().describe('Override the proposed TTL on accept'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ id, title, content, category, project, ttl }) => {
         try {
             const ref = await ratifyProposal(contextDir, id, { title, content, category, project, ttl });
@@ -294,9 +399,13 @@ export function createLoomServer(config) {
             return { content: [{ type: 'text', text: `Proposal #${id} refused — ${reason}. It remains pending.` }] };
         }
     });
-    server.tool('memory_reject', 'Discard a pending proposal without committing it. Deletes the staging row; ' +
-        'no memory is written. Use this for drafts that should not become canon.', {
-        id: z.number().int().positive().describe('Proposal id (from memory_proposals)'),
+    server.registerTool('memory_reject', {
+        description: 'Discard a pending proposal without committing it. Deletes the staging row; ' +
+            'no memory is written. Use this for drafts that should not become canon.',
+        inputSchema: {
+            id: z.number().int().positive().describe('Proposal id (from memory_proposals)'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ id }) => {
         const removed = rejectProposal(contextDir, id);
         return {
@@ -307,259 +416,237 @@ export function createLoomServer(config) {
         };
     });
     // ─── Identity Update ────────────────────────────────────────────────────────
-    server.tool('update_identity', 'Update your self-model or preferences with section-level precision. ' +
-        'Targets H2 sections in identity files. Call without section/content to ' +
-        'list available sections. IDENTITY.md (the creed) is immutable — only ' +
-        'self-model and preferences can be edited.', {
-        file: z.enum(['self-model', 'preferences']).describe('Which identity file to update: "self-model" or "preferences"'),
-        section: z.string().optional().describe('H2 section name to target. Omit to list all sections.'),
-        content: z.string().optional().describe('New content for the section (replaces everything under the H2 header)'),
-        mode: z.enum(['replace', 'append']).optional().describe('"replace" updates an existing section (default), "append" adds a new section'),
+    server.registerTool('update_identity', {
+        description: 'Update your self-model or preferences with section-level precision. ' +
+            'Targets H2 sections in identity files. Call without section/content to ' +
+            'list available sections. IDENTITY.md (the creed) is immutable — only ' +
+            'self-model and preferences can be edited.',
+        inputSchema: {
+            file: z.enum(['self-model', 'preferences']).describe('Which identity file to update: "self-model" or "preferences"'),
+            section: z.string().optional().describe('H2 section name to target. Omit to list all sections.'),
+            content: z.string().optional().describe('New content for the section (replaces everything under the H2 header)'),
+            mode: z.enum(['replace', 'append']).optional().describe('"replace" updates an existing section (default), "append" adds a new section'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
     }, async ({ file, section, content, mode }) => {
         const result = await updateIdentity(contextDir, { file, section, content, mode });
         return { content: [{ type: 'text', text: result }] };
     });
     // ─── Bootstrap ──────────────────────────────────────────────────────────────
-    server.tool('bootstrap', 'Initialize a new loom identity from scratch. Generates IDENTITY.md, preferences.md, ' +
-        'and self-model.md from an onboarding interview, then returns setup instructions for ' +
-        'the requested runtimes. The interview is four questions — the user\'s name, the ' +
-        "agent's name, a one-line purpose, a one-line voice; everything structural (continuity " +
-        'model, memory tiers, reflection, honesty) is written by the scaffold, so do not ask ' +
-        'for it. Will not overwrite existing files unless force is true.', {
-        user: z.string().optional().describe("The human this agent works with — their name, not the agent's"),
-        name: z.string().describe('Name for the agent identity (e.g. "Aria")'),
-        purpose: z.string().describe('What this agent exists to do — its reason for being, one line'),
-        voice: z.string().describe('Communication style and personality, one line'),
-        preferences: z.string().optional().describe('Seed preferences about the user or working style'),
-        clients: z.array(z.string()).optional().describe('Runtimes to generate setup instructions for: "claude-code", "gemini-cli", or any custom runtime name (uses a generic template)'),
-        force: z.boolean().optional().describe('Overwrite existing identity files (default: false)'),
+    server.registerTool('bootstrap', {
+        description: 'Initialize a new loom identity from scratch. Generates IDENTITY.md, preferences.md, ' +
+            'and self-model.md from an onboarding interview, then returns setup instructions for ' +
+            'the requested runtimes. The interview is four questions — the user\'s name, the ' +
+            "agent's name, a one-line purpose, a one-line voice; everything structural (continuity " +
+            'model, memory tiers, reflection, honesty) is written by the scaffold, so do not ask ' +
+            'for it. Will not overwrite existing files unless force is true.',
+        inputSchema: {
+            user: z.string().optional().describe("The human this agent works with — their name, not the agent's"),
+            name: z.string().describe('Name for the agent identity (e.g. "Aria")'),
+            purpose: z.string().describe('What this agent exists to do — its reason for being, one line'),
+            voice: z.string().describe('Communication style and personality, one line'),
+            preferences: z.string().optional().describe('Seed preferences about the user or working style'),
+            clients: z.array(z.string()).optional().describe('Runtimes to generate setup instructions for: "claude-code", "gemini-cli", or any custom runtime name (uses a generic template)'),
+            force: z.boolean().optional().describe('Overwrite existing identity files (default: false)'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
     }, async ({ user, name, purpose, voice, preferences, clients, force }) => {
         const result = await bootstrap(contextDir, { user, name, purpose, voice, preferences, clients, force });
         return { content: [{ type: 'text', text: result }] };
     });
     // ─── Harness manifests ──────────────────────────────────────────────────────
-    server.tool('harness_init', 'Scaffold a harness manifest at <contextDir>/harnesses/<name>.md from the template ' +
-        '(see stack spec v1 §4.7). Call this when identity() reports a missing manifest for the ' +
-        'current harness. Idempotent: skip-exists by default; overwrite: true replaces.\n\n' +
-        'When `target` is supplied, also writes a loom-managed block (bounded by ' +
-        '<!-- loom:start / loom:end --> markers with an embedded <!-- loom:hash --> line) ' +
-        'into that file — typically the project CLAUDE.md. Re-runnable: the block is ' +
-        'left unchanged when already present and intact ("no-change"), reinstalled when ' +
-        'missing or corrupted ("created" / "updated"). Pass an absolute path or a path ' +
-        'relative to the current working directory.', {
-        name: z.string().describe('Harness name (e.g. "claude-code", "codex", "gemini-cli")'),
-        overwrite: z.boolean().optional().describe('Replace existing manifest (default: false)'),
-        target: z.string().optional().describe('Path to the dotfile to inject the managed loom block into (e.g. an absolute path ' +
-            'to CLAUDE.md / AGENTS.md / GEMINI.md). When omitted only the harness manifest ' +
-            'is scaffolded.'),
+    server.registerTool('harness_init', {
+        description: 'Scaffold a harness manifest at <contextDir>/harnesses/<name>.md from the template ' +
+            '(see stack spec v1 §4.7). Call this when identity() reports a missing manifest for the ' +
+            'current harness. Idempotent: skip-exists by default; overwrite: true replaces.\n\n' +
+            'When `target` is supplied, also writes a loom-managed block (bounded by ' +
+            '<!-- loom:start / loom:end --> markers with an embedded <!-- loom:hash --> line) ' +
+            'into that file — typically the project CLAUDE.md. Re-runnable: the block is ' +
+            'left unchanged when already present and intact ("no-change"), reinstalled when ' +
+            'missing or corrupted ("created" / "updated"). Pass an absolute path or a path ' +
+            'relative to the current working directory.',
+        inputSchema: {
+            name: z.string().describe('Harness name (e.g. "claude-code", "codex", "gemini-cli")'),
+            overwrite: z.boolean().optional().describe('Replace existing manifest (default: false)'),
+            target: z.string().optional().describe('Path to the dotfile to inject the managed loom block into (e.g. an absolute path ' +
+                'to CLAUDE.md / AGENTS.md / GEMINI.md). When omitted only the harness manifest ' +
+                'is scaffolded.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ name, overwrite, target }) => {
         const text = await harnessInit(contextDir, { name, overwrite, target });
         return { content: [{ type: 'text', text }] };
     });
-    server.tool('harness_describe', 'Self-describe the CURRENTLY CONNECTED harness: write its manifest at ' +
-        '<contextDir>/harnesses/<key>.md (see stack spec v1 §4.7). Call this when ' +
-        'identity() reports an onboarding block for an unknown runtime. The target is ' +
-        'derived from your own MCP clientInfo.name — you can only describe yourself, ' +
-        'not another harness. Re-runnable: overwrites the manifest each time. The body ' +
-        'should cover: tool surface / prefixes, sandbox & filesystem, delegation ' +
-        'primitive, scheduling, session search, memory layers, and gotchas.', {
-        content: z.string().describe('The manifest body (markdown). Frontmatter is stamped automatically.'),
-        version: z.string().optional().describe('Manifest version stamp (default "0.1").'),
+    server.registerTool('harness_describe', {
+        description: 'Self-describe the CURRENTLY CONNECTED harness: write its manifest at ' +
+            '<contextDir>/harnesses/<key>.md (see stack spec v1 §4.7). Call this when ' +
+            'identity() reports an onboarding block for an unknown runtime. The target is ' +
+            'derived from your own MCP clientInfo.name — you can only describe yourself, ' +
+            'not another harness. Re-runnable: overwrites the manifest each time. The body ' +
+            'should cover: tool surface / prefixes, sandbox & filesystem, delegation ' +
+            'primitive, scheduling, session search, memory layers, and gotchas.',
+        inputSchema: {
+            content: z.string().describe('The manifest body (markdown). Frontmatter is stamped automatically.'),
+            version: z.string().optional().describe('Manifest version stamp (default "0.1").'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ content, version }) => {
         const peer = server.server.getClientVersion()?.name;
         const text = await harnessDescribe(contextDir, { content, version }, peer);
         return { content: [{ type: 'text', text }] };
     });
     // ─── Knowledge ──────────────────────────────────────────────────────────────
-    server.tool('knowledge_write', 'Upsert a knowledge page by slug. Two classes:\n' +
-        '  world/ (default) — facts true independent of us. Domain = "music/gear", "software/loom", etc.\n' +
-        '  ours/  — Art-created artifacts, revised-in-place (breakbrain density model, homelab design,\n' +
-        '            wake-chain spec, script templates). Domain starts with "ours/", e.g. "ours/art-ops".\n' +
-        'On an existing slug: body REPLACES by default (mode: "append" adds to it instead), ' +
-        'title/domain follow the write, citations always appended with exact-duplicate dedup — safe to re-send.\n' +
-        'Epistemic gate (§E1):\n' +
-        '  • conversation-only citations → provisional (both classes).\n' +
-        '  • any repo citation → internal (ours/ class; repo = git path / commit / live-system probe).\n' +
-        '  • any web citation, no repo → sourced (world/ default).\n' +
-        'World filing test: knowledge must be true independent of Jonathan. For our own artifacts use ours/.', {
-        title: z.string().describe('Page title — the entity name (e.g. "Mutable Instruments Rings") or artifact name (e.g. "breakbrain density model")'),
-        domain: z.string().describe('Domain tag. World class: "music/eurorack", "programming/typescript". ' +
-            'Ours class: prefix with "ours/" — e.g. "ours/art-ops", "ours/breakbrain", "ours/homelab". ' +
-            'Hierarchical string; sub-domains queryable via prefix filter.'),
-        body: z.string().describe('Synthesized markdown body for the entity or artifact page (max 64 KB)'),
-        slug: z.string().optional().describe('Entity key for upsert — stable URL-safe identifier. ' +
-            'Derived from title if omitted.'),
-        freshness_anchor: z.string().optional().describe('The version/date the page\'s claims are valid as-of — e.g. "Syntakt OS 1.21" for a ' +
-            'device, "as of 2026-05" for a topic, or "t-81 / 2026-08-31" for an ours/ artifact. ' +
-            'Drives the verification engine: a page is re-verified when this anchor moves or the freshness SLA elapses.'),
-        mode: z.enum(['replace', 'append']).optional().describe('Body combine mode when the slug already exists: "replace" (default) overwrites the ' +
-            'stored body; "append" adds this body after the existing one. Citations are appended ' +
-            '(deduped) in both modes. Ignored when creating a new page.'),
-        citations: z.array(z.object({
-            claim: z.string().describe('The assertion this citation supports'),
-            source_kind: z.enum(['web', 'loom_memory', 'conversation', 'repo']).describe('web = external URL; loom_memory = opaque memory ref; conversation = session distillation; ' +
-                'repo = git repo path / commit / live-system probe (ours/ class)'),
-            source_locator: z.string().optional().describe('URL, memory ref, session ID, or repo path + commit hash'),
-            excerpt: z.string().describe('Inline supporting quote or repo excerpt — link-rot insurance (max 4 KB)'),
-        })).describe('Support citations. At least one required. ' +
-            'All-conversation → provisional. Any repo → internal (ours/). Any web → sourced.'),
-        created_by: z.string().optional().describe('ours/ class: who created or last owned this artifact (e.g. "art", "jonathan"). ' +
-            'Preserved across upserts when omitted.'),
-        version: z.string().optional().describe('ours/ class: artifact version or revision tag (e.g. "v2", "2026-08-31", "t-81"). ' +
-            'Preserved across upserts when omitted.'),
-    }, async ({ title, domain, body, slug, freshness_anchor, mode, citations, created_by, version }) => {
-        const result = await knowledgeWrite(contextDir, { title, domain, body, slug, freshness_anchor, mode, citations, created_by, version });
-        return { content: [{ type: 'text', text: result }] };
-    });
-    server.tool('knowledge_recall', 'Search the knowledge store with LIKE matching over title, body, and domain, ' +
-        'or fetch one page exactly by slug. Never surfaces archived pages. Two detail ' +
-        'tiers: "full" returns whole entity pages (the synthesis unit) and stamps ' +
-        'last_accessed/hit_count; "index" returns compact slug/domain/snippet entries ' +
-        'without stamping. Defaults: full when a query is given, index when browsing ' +
-        'without one. Full output is size-guarded — overflow results degrade to index ' +
-        'entries; recall by slug to read them. Prefer slug over query when you know ' +
-        'the page — token matching can hit cross-references in other pages\' bodies.', {
-        slug: z.string().optional().describe('Exact-slug lookup — returns that single page in full detail and stamps ' +
-            'access. Takes precedence over query/domain/limit.'),
-        query: z.string().optional().describe('Search terms — matched against title, body, and domain. ' +
-            'Omit to browse (returns an index of non-archived pages up to limit).'),
-        domain: z.string().optional().describe('Filter by domain prefix, inclusive of the exact domain ' +
-            '(e.g. "music/gear" matches "music/gear" and "music/gear/elektron")'),
-        limit: z.number().int().positive().optional().describe('Maximum results to return (default: 10)'),
-        detail: z.enum(['index', 'full']).optional().describe('Output tier override. "index": compact listing, no body, no access stamping. ' +
-            '"full": whole pages with citations. Default: full with a query, index without.'),
-        sort_by_verified: z.boolean().optional().describe('Stale-first ordering for the verification engine: verified_at ASC with ' +
-            'never-verified pages first. Index entries gain a "verified:" stamp so the ' +
-            'SLA filter can run from the listing alone.'),
-    }, async ({ slug, query, domain, limit, detail, sort_by_verified }) => {
-        const result = await knowledgeRecall(contextDir, { slug, query, domain, limit, detail, sort_by_verified });
+    // The local identity — LOOM_IDENTITY, else the context dir's real name —
+    // since this server runs as whichever identity owns contextDir, not only
+    // Art. The standalone knowledge-only service (knowledge-http-server.ts)
+    // resolves identity per-connection from its per-identity bearer token instead.
+    registerKnowledgeTools(server, { contextDir, gapsDir, identity: resolveIdentityName(contextDir), personCards: true });
+    server.registerTool('memory_history', {
+        description: 'Body-revision history for a memory. update() snapshots the displaced body into ' +
+            'memory_revisions before overwriting it — this tool is the read surface. ' +
+            'Two modes: ref alone lists snapshots (metadata only — id, op, replaced_at, char count); ' +
+            'ref + revision_id reads one snapshot\'s full content. ' +
+            'To put a snapshot back, use memory_revision_restore.',
+        inputSchema: {
+            ref: z.string().describe('Ref of the memory (category/title slug).'),
+            revision_id: z.number().int().positive().optional().describe('Revision to read (from the listing). Omit to list all revisions.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ ref, revision_id }) => {
+        const result = await memoryHistory(contextDir, { ref, revision_id });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_maintain', 'Read-only health report for the knowledge store. Three branches: ' +
-        '(1) expansion candidates — thin body + high hit_count (needs deepening); ' +
-        '(2) cold pages — not accessed recently (unused or undiscovered); ' +
-        '(3) misfile audit — provisional sourcing or conversation-only citations ' +
-        '(world/ class: should be in the memory store instead; ours/ class with internal sourcing are NOT misfiles — they are correct). ' +
-        'Pair with knowledge_write to act on findings.', {
-        expansion_hit_threshold: z.number().int().nonnegative().optional().describe('hit_count floor for expansion candidates (default 3; 0 considers every page)'),
-        thin_body_threshold: z.number().int().positive().optional().describe('body char ceiling to consider a page thin (default 500)'),
-        cold_days: z.number().int().positive().optional().describe('Days without access before a page is cold (default 30)'),
-    }, async ({ expansion_hit_threshold, thin_body_threshold, cold_days }) => {
-        const result = await knowledgeMaintain(contextDir, {
-            expansionHitThreshold: expansion_hit_threshold,
-            thinBodyThreshold: thin_body_threshold,
-            coldDays: cold_days,
-        });
+    server.registerTool('memory_revision_restore', {
+        description: 'Restore a snapshotted memory body back onto the memory. ' +
+            'Snapshots the current body first, so restore is never destructive. ' +
+            'Use memory_history to list revision IDs before calling this.',
+        inputSchema: {
+            ref: z.string().describe('Ref of the memory (category/title slug).'),
+            revision_id: z.number().int().positive().describe('Id of the revision to restore (from memory_history listing).'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ ref, revision_id }) => {
+        const result = await memoryRevisionRestore(contextDir, { ref, revision_id });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_archive', 'Soft-retire a knowledge page: set its status to archived with an optional tombstone note. ' +
-        'Archived pages are excluded from knowledge_recall and knowledge_maintain but remain ' +
-        'in the database and are fully recoverable via knowledge_restore. ' +
-        'Use this instead of deletion when the page may need to be audited or recovered. ' +
-        'For deduplication merges, prefer knowledge_supersede which archives and records the relationship.', {
-        slug: z.string().describe('Slug of the knowledge page to archive'),
-        note: z.string().optional().describe('Tombstone note: why this page is being retired'),
-    }, async ({ slug, note }) => {
-        const result = await knowledgeArchive(contextDir, { slug, note });
+    // ─── People ─────────────────────────────────────────────────────────────────
+    // Person cards (docs/specs/person-cards.md): the condensed current state of a
+    // human the agent works with. Current state, overwritten; revisions keep the
+    // past. Descriptive only — never an authorization surface. Schemas are
+    // strict: a raw shape strips unknown keys, and a misspelled section on a
+    // merge: false write would then silently clear state (PR143 review).
+    const cardValue = z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]);
+    const slugParam = z.string().describe('Person slug: lowercase [a-z0-9-], e.g. "patrick-kells".');
+    server.registerTool('person_write', {
+        description: 'Write a person card — the condensed current state of what you know about one human ' +
+            '(not a knowledge page, not the memories: those stay the evidence). merge (default true) ' +
+            'merges where/how one level deep (a field passed as null is removed), and replaces name, ' +
+            'summary and may when passed; merge: false makes the card exactly what was passed. ' +
+            'Passing summary says "I re-read the evidence and this is still right" and moves ' +
+            'synthesized_at. Reserved keys (tier, field, projects, scope, trust) are rejected: gates ' +
+            'stay in the harness. Worker bodies must not call this — cards are written by Art.',
+        inputSchema: z.object({
+            slug: slugParam,
+            name: z.string().optional().describe('Display name (required on create and on merge: false), ≤ 80 chars.'),
+            summary: z.string().optional().describe('Short synthesized summary, ≤ 1,200 chars.'),
+            where: z.record(z.string(), z.union([
+                z.object({
+                    value: cardValue,
+                    verified_at: z.string().optional(),
+                    source: z.string().optional(),
+                    stale_after_days: z.number().int().optional(),
+                }).passthrough(),
+                z.null(),
+            ])).optional().describe('Where the person is in each system: field -> {value, verified_at?, source?, stale_after_days?}. ' +
+                'null removes a field (merge writes only).'),
+            how: z.record(z.string(), z.union([cardValue, z.null()])).optional().describe('How to work with them: field -> value (e.g. tz, mode, loop_in). null removes a field.'),
+            may: z.array(z.object({ text: z.string(), source: z.string() }).passthrough()).optional().describe('What they were said to be allowed to do, each with its source. Descriptive, not a grant. Replaces the whole list.'),
+            merge: z.boolean().optional().describe('Default true. false: the card becomes exactly what was passed.'),
+        }).strict(),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async (input) => {
+        const result = await personWrite(contextDir, input);
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_restore', 'Restore a previously archived knowledge page back to active status. ' +
-        'Clears the archive flag and tombstone note. The page becomes visible ' +
-        'to knowledge_recall and knowledge_maintain again.', {
-        slug: z.string().describe('Slug of the archived knowledge page to restore'),
-    }, async ({ slug }) => {
-        const result = await knowledgeRestore(contextDir, { slug });
+    server.registerTool('person_verify', {
+        description: 'Stamp where fields on a person card as checked: sets verified_at (default now) and, if ' +
+            'passed, source. Values are not changed. All-or-nothing: an unknown field rejects the call. ' +
+            'A failed check is recorded by not stamping.',
+        inputSchema: z.object({
+            slug: slugParam,
+            fields: z.array(z.string()).describe('where field names to stamp.'),
+            verified_at: z.string().optional().describe('ISO-8601 UTC; default now; not in the future.'),
+            source: z.string().optional().describe('What you checked against, e.g. "pond /api/tadpoles".'),
+        }).strict(),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ slug, fields, verified_at, source }) => {
+        const result = await personVerify(contextDir, { slug, fields, verified_at, source });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_move', 'Re-key or re-domain a knowledge page in place — same row, same uuid, citations and verification history preserved. ' +
-        'Three modes: (1) Single-page: provide slug + new_slug and/or new_domain. ' +
-        'Slug rename writes a supersessions pointer (old→new) unless leave_pointer=false. ' +
-        'If new_slug already exists, the call is rejected — use knowledge_merge instead. ' +
-        '(2) Batch by slug list: provide slugs array + new_domain to re-home multiple pages atomically. ' +
-        '(3) Batch by domain prefix: provide from_domain_prefix + to_domain_prefix to re-home a whole subtree in one transaction.', {
-        slug: z.string().optional().describe('Current slug of the page to move (single-page mode)'),
-        new_slug: z.string().optional().describe('New slug (re-slug). Collision with an existing page is rejected — use knowledge_merge instead.'),
-        new_domain: z.string().optional().describe('New domain for the page (single-page re-domain or shared target for batch-by-slugs mode)'),
-        leave_pointer: z.boolean().optional().describe('Write a supersessions pointer old_slug→new_slug when the slug changes. Default true.'),
-        slugs: z.array(z.string()).optional().describe('Batch mode: list of slugs to re-domain. Requires new_domain. Atomic — rolls back on any missing slug.'),
-        from_domain_prefix: z.string().optional().describe('Batch prefix mode: domain prefix to replace (e.g. "gear/elektron"). Requires to_domain_prefix.'),
-        to_domain_prefix: z.string().optional().describe('Batch prefix mode: replacement domain prefix (e.g. "instruments/elektron").'),
-    }, async ({ slug, new_slug, new_domain, leave_pointer, slugs, from_domain_prefix, to_domain_prefix }) => {
-        const result = await knowledgeMove(contextDir, {
-            slug, new_slug, new_domain, leave_pointer, slugs, from_domain_prefix, to_domain_prefix,
-        });
+    server.registerTool('person_archive', {
+        description: 'Soft-retire a person card with a tombstone (who, when, why). An archived card is left ' +
+            'out of identity\'s room block and person_list, and rejects writes until person_restore.',
+        inputSchema: z.object({
+            slug: slugParam,
+            reason: z.string().describe('Why the card is being retired, ≤ 200 chars.'),
+        }).strict(),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ slug, reason }) => {
+        const result = await personArchive(contextDir, { slug, reason });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_merge', 'Consolidate 2+ knowledge pages into one canonical page. ' +
-        'Re-parents all citations from source pages to the target, deduplicating by (claim, source_kind, source_locator, excerpt). ' +
-        'Takes MAX(verified_at) across all pages. ' +
-        'Losers are superseded: archived with a tombstone and a supersessions pointer to the target. ' +
-        'Loser bodies are returned in the result for curator review; set append_loser_bodies=true to concatenate them. ' +
-        'Use knowledge_write first if the target body needs updating before merging. ' +
-        'Distinct from knowledge_supersede (1:1 pointer, no citation consolidation) — ' +
-        'use merge when consolidating data from multiple pages into one.', {
-        source_slugs: z.array(z.string()).describe('Slugs of the pages to merge into the target (all must exist)'),
-        target_slug: z.string().describe('Slug of the canonical target page that survives the merge (must already exist)'),
-        note: z.string().optional().describe('Optional note about this merge, stored in supersession tombstones on the losers'),
-        hard_delete_losers: z.boolean().optional().describe('Hard-delete losers after archiving them. Losers are archived (supersession pointer written) then DELETEd from the database, cascading their citations.'),
-        append_loser_bodies: z.boolean().optional().describe('Append loser page bodies to the target body under section markers (default false). Off by default — curator normally hand-merges body content.'),
-    }, async ({ source_slugs, target_slug, note, hard_delete_losers, append_loser_bodies }) => {
-        const result = await knowledgeMerge(contextDir, {
-            source_slugs, target_slug, note, hard_delete_losers, append_loser_bodies,
-        });
+    server.registerTool('person_restore', {
+        description: 'Reactivate an archived person card, fields intact.',
+        inputSchema: z.object({ slug: slugParam }).strict(),
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ slug }) => {
+        const result = await personRestore(contextDir, { slug });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_supersede', 'Mark one knowledge page as superseded by another, then archive the old page. ' +
-        'Records the supersession relationship in the supersessions table. ' +
-        'This is the dedup-merge primitive: write the canonical page with knowledge_write, ' +
-        'then call knowledge_supersede(old_slug=loser, new_slug=canonical). ' +
-        'Both pages must already exist. old_slug is archived with a tombstone pointing to new_slug.', {
-        old_slug: z.string().describe('Slug of the page being retired (the duplicate or loser)'),
-        new_slug: z.string().describe('Slug of the canonical replacement page (must already exist)'),
-        note: z.string().optional().describe('Optional note explaining the merge or supersession decision'),
-    }, async ({ old_slug, new_slug, note }) => {
-        const result = await knowledgeSupersede(contextDir, { old_slug, new_slug, note });
+    server.registerTool('person', {
+        description: 'Read one person card: {found, rendered, card, archived, updated, synthesized_at}. ' +
+            'A missing card is {found: false}, not an error. where fields carry a freshness marker: ' +
+            '[ok], [unverified], or [STALE <n>d] — never trust a stale one without re-checking.',
+        inputSchema: z.object({
+            slug: slugParam,
+            include_archived: z.boolean().optional().describe('Return an archived card in full (default false).'),
+        }).strict(),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ slug, include_archived }) => {
+        const result = await person(contextDir, { slug, include_archived });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_purge', 'Hard-delete one or more archived knowledge pages and cascade their citations. ' +
-        'Archive-first guard: rejects any page that is not already archived — call knowledge_archive first. ' +
-        'All slugs must be archived; a mixed list (any active) rejects the entire batch with no mutation. ' +
-        'confirm: true is required explicitly to prevent accidental irreversible deletes. ' +
-        'Supersession pointers in the supersessions table are NOT removed (historical record preserved). ' +
-        'Use this to clean up tombstoned cruft after merge/supersede workflows — not for retiring active pages.', {
-        slugs: z.array(z.string()).describe('Slugs of archived pages to hard-delete. All must have status=archived.'),
-        confirm: z.literal(true).describe('Must be explicitly true — required safety gate for an irreversible operation.'),
-    }, async ({ slugs, confirm }) => {
-        const result = await knowledgePurge(contextDir, { slugs, confirm });
+    server.registerTool('person_list', {
+        description: 'List person cards with slug, name, archived, updated, synthesized_at, stale and unverified ' +
+            'field counts, and memories_since_synthesis (tagged user memories newer than the summary — ' +
+            'how the consolidation lane finds summaries that have fallen behind).',
+        inputSchema: z.object({
+            include_archived: z.boolean().optional().describe('Include archived cards (default false).'),
+        }).strict(),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ include_archived }) => {
+        const result = await personList(contextDir, { include_archived });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_verify', 'Stamp a knowledge page as verified WITHOUT touching its body — sets verified_at ' +
-        'and optionally freshness_anchor. This is the verification engine\'s primitive: ' +
-        'use it (never knowledge_write) to record "claims still hold". An optional note ' +
-        'appends a dated "## Verification" section to the body (append-only, single-page ' +
-        'mode). Batch mode (slugs) stamps many pages with a shared timestamp; archived ' +
-        'pages are rejected; a batch with any unknown slug is rejected whole.', {
-        slug: z.string().optional().describe('Single-page mode: slug of the page to verify.'),
-        slugs: z.array(z.string()).optional().describe('Batch mode: stamp many pages at once. Mutually exclusive with slug; ' +
-            'note and freshness_anchor are not allowed in batch mode.'),
-        verified_at: z.string().optional().describe('ISO timestamp to stamp. Defaults to now.'),
-        freshness_anchor: z.string().optional().describe('New freshness anchor (e.g. "Syntakt OS 1.41"). Preserved when omitted. Single-page mode only.'),
-        note: z.string().optional().describe('Optional verification note — appended to the body as a "## Verification — <date>" ' +
-            'section. Never replaces the body. Single-page mode only.'),
-    }, async ({ slug, slugs, verified_at, freshness_anchor, note }) => {
-        const result = await knowledgeVerify(contextDir, { slug, slugs, verified_at, freshness_anchor, note });
+    server.registerTool('person_history', {
+        description: 'Revision history of a person card, newest first: id, op, replaced_at. Every stored change ' +
+            'snapshots the previous card; the newest 10 are kept. Use person_revision_restore to put one back.',
+        inputSchema: z.object({ slug: slugParam }).strict(),
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ slug }) => {
+        const result = await personHistory(contextDir, { slug });
         return { content: [{ type: 'text', text: result }] };
     });
-    server.tool('knowledge_history', 'Body-revision history for a knowledge page. Replace-writes snapshot the displaced ' +
-        'body into page_revisions (newest kept, capped per page) — this tool is the recovery ' +
-        'surface. Three modes: slug alone lists snapshots (metadata only); slug + revision_id ' +
-        'reads one snapshot\'s full body; adding restore: true puts that body back on the page ' +
-        '(the displaced body is snapshotted first, so restore is never destructive).', {
-        slug: z.string().describe('Slug of the knowledge page.'),
-        revision_id: z.number().int().positive().optional().describe('Revision to read (from the listing). Combine with restore: true to put it back.'),
-        restore: z.boolean().optional().describe('Restore the revision\'s body onto the page. Requires revision_id.'),
-    }, async ({ slug, revision_id, restore }) => {
-        const result = await knowledgeHistory(contextDir, { slug, revision_id, restore });
+    server.registerTool('person_revision_restore', {
+        description: 'Put a person card back to a revision from person_history (card and its synthesized_at). ' +
+            'Snapshots the current card first, so it is never destructive. Archive state is unchanged.',
+        inputSchema: z.object({
+            slug: slugParam,
+            revision_id: z.number().int().positive().describe('Revision id from person_history.'),
+        }).strict(),
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ slug, revision_id }) => {
+        const result = await personRevisionRestore(contextDir, { slug, revision_id });
         return { content: [{ type: 'text', text: result }] };
     });
     // MCP-App render probe — env-gated, throwaway. Not part of the tool surface