neotoma 0.9.0 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 Your agents forget. Neotoma makes them remember.
 
-Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
+Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
 
 **[neotoma.io](https://neotoma.io)** · **[Evaluate](https://neotoma.io/evaluate)** · **[Install](https://neotoma.io/install)** · **[Documentation](https://neotoma.io/docs)**
 
@@ -38,6 +38,7 @@ graph LR
   MCP --> ChatGPT
   MCP --> Cursor
   MCP --> OpenClaw
+  MCP --> IronClaw
 ```
 
 - **Deterministic.** Same observations always produce the same versioned entity snapshots. No ordering sensitivity.
@@ -51,7 +52,7 @@ graph LR
 | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
 | **Privacy-first**  | Your data stays local. Never used for training. User-controlled storage, optional encryption at rest. Full export and deletion control. |
 | **Deterministic**  | Same input always produces same output. Schema-first extraction, hash-based entity IDs, full provenance. No silent mutation.            |
-| **Cross-platform** | One memory graph across Claude, ChatGPT, Cursor, OpenClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
+| **Cross-platform** | One memory graph across Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
 
 ## State guarantees
 
@@ -121,14 +122,14 @@ Three interfaces. One state invariant. Every interface provides the same determi
 | Interface      | Description                                                                                                                    |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | **REST API**   | Full HTTP interface for application integration. Entities, relationships, observations, schema, timeline, and version history. |
-| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
+| **MCP Server** | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, IronClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
 | **CLI**        | Command-line for scripting and direct access. Inspect entities, replay timelines, and manage state from the terminal.          |
 
 All three map to the same OpenAPI-backed operations. MCP tool calls log the equivalent CLI invocation.
 
 ## Who this is for
 
-People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
+People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, IronClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
 
 | Mode | What you're doing | The tax you pay without Neotoma | What you get back |
 | ---- | ----------------- | ------------------------------- | ----------------- |
@@ -155,7 +156,7 @@ Schema is flexible — store any entity type with whatever fields the message im
 
 ## Current status
 
-**Version:** v0.4.2 · **Releases:** 13 · **License:** MIT
+**Version:** v0.9.1 · **Releases:** 26 · **License:** MIT
 
 ### What is guaranteed (even in preview)
 
@@ -188,6 +189,7 @@ Neotoma stores user data and requires secure configuration.
 
 ```bash
 npm run dev          # MCP server (stdio)
+npm run dev:mcp:dev-shim  # stable stdio shim for MCP source iteration
 npm run dev:ui       # Frontend
 npm run dev:server   # API only (MCP at /mcp)
 npm run dev:full     # API + UI + build watch
@@ -216,9 +218,11 @@ npm test
 
 Neotoma exposes state via MCP. Local storage only in preview. Local built-in auth.
 
-**Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw)
+**Setup guides:** [Cursor](https://neotoma.io/neotoma-with-cursor) · [Claude Code](https://neotoma.io/neotoma-with-claude-code) · [Claude](https://neotoma.io/neotoma-with-claude) · [ChatGPT](https://neotoma.io/neotoma-with-chatgpt) · [Codex](https://neotoma.io/neotoma-with-codex) · [OpenCode](docs/integrations/hooks/opencode.md) · [OpenClaw](https://neotoma.io/neotoma-with-openclaw) · [IronClaw](https://neotoma.io/neotoma-with-ironclaw)
 
-**Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
+For local source iteration, use the stable dev shim (`scripts/run_neotoma_mcp_stdio_dev_shim.sh` or `npm run dev:mcp:dev-shim`) instead of pointing installed MCP clients at a `tsx watch` stdio process. The shim keeps the client-facing JSON-RPC stream stable and asks clients to refresh or reconnect when the tool interface changes.
+
+**Agent behavior contract:** Store first, retrieve before storing, extract entities from user input, create tasks for commitments, and attach bounded host context such as repository name/root scope when available. Full instructions: [MCP instructions](docs/developer/mcp/instructions.md) and [CLI agent instructions](docs/developer/cli_agent_instructions.md).
 
 **Representative actions:** `store`, `retrieve_entities`, `retrieve_entity_snapshot`, `merge_entities`, `list_observations`, `create_relationship`, `list_relationships`, `list_timeline_events`, `retrieve_graph_neighborhood`. Full list: [MCP spec](docs/specs/MCP_SPEC.md).
 

package/dist/actions.d.ts

@@ -22,6 +22,14 @@ export declare function isLocalRequest(req: express.Request): boolean;
  * a different authority. See src/middleware/aauth_verify.ts.
  */
 export declare function canonicalAauthAuthority(): string;
+type StoreRelationshipRef = {
+    relationship_type: string;
+    source_index?: number;
+    target_index?: number;
+    source_entity_id?: string;
+    target_entity_id?: string;
+    metadata?: Record<string, unknown>;
+};
 export declare function storeStructuredForApi(params: {
     userId: string;
     entities: Record<string, unknown>[];
@@ -29,11 +37,7 @@ export declare function storeStructuredForApi(params: {
     observationSource?: import("./shared/action_schemas.js").ObservationSource;
     idempotencyKey: string;
     originalFilename?: string;
-    relationships?: Array<{
-        relationship_type: string;
-        source_index: number;
-        target_index: number;
-    }>;
+    relationships?: StoreRelationshipRef[];
     commit?: boolean;
     strict?: boolean;
 }): Promise<{
@@ -92,4 +96,5 @@ export declare function startHTTPServer(): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
     port: number;
 } | undefined>;
+export {};
 //# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAiK9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAif7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AA6nHD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cAkfS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA9IV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA8E3B;AA29DD,wBAAsB,eAAe;;;eA2FpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAmK9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAif7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AA4sHD,KAAK,oBAAoB,GAAG;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cA+fS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA3JV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA2F3B;AAuhED,wBAAsB,eAAe;;;eA2FpC"}

package/dist/actions.js

@@ -43,7 +43,7 @@ import { resolveSandboxReportTransport } from "./services/sandbox/transport.js";
 import { getSqliteDb } from "./repositories/sqlite/sqlite_client.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.js";
 import { isOauthKeyCredentialValid, normalizeOauthNextPath, OAuthKeySessionStore, } from "./services/oauth_key_gate.js";
-import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
+import { AnalyzeSchemaCandidatesRequestSchema, CorrectEntityRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, StoreRequestSchema, StoreUnstructuredRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
@@ -51,8 +51,9 @@ import { prepareEntitySnapshotWithEmbedding, upsertEntitySnapshotWithEmbedding,
 import { readOpenApiActionsFile, readOpenApiFile } from "./shared/openapi_file.js";
 import { buildSmitheryServerCard } from "./mcp_server_card.js";
 import { listRecentRecordActivity, parseRecordActivityTypesQuery, } from "./services/recent_record_activity.js";
-import { listRecentConversations } from "./services/recent_conversations.js";
+import { getRecentConversationById, listRecentConversations } from "./services/recent_conversations.js";
 import { listConversationTurns, getConversationTurn, } from "./services/conversation_turn.js";
+import { buildComplianceScorecard } from "./services/compliance/scorecard.js";
 import { getAgent, listAgentRecords, listAgents } from "./services/agents_directory.js";
 export const app = express();
 // Trust proxy headers (required for express-rate-limit when X-Forwarded-For is present)
@@ -1688,21 +1689,38 @@ app.post("/mcp/oauth/token", oauthTokenLimit, express.urlencoded({ extended: tru
     try {
         const grant_type = req.body?.grant_type;
         const code = req.body?.code;
+        const refresh_token = req.body?.refresh_token;
         logger.info("[MCP OAuth] Token request received", {
             grant_type: grant_type ?? null,
             has_code: typeof code === "string" && code.length > 0,
             code_hint: typeof code === "string" ? code.slice(0, 8) : null,
+            has_refresh_token: typeof refresh_token === "string" && refresh_token.length > 0,
             host: req.header("host") ?? null,
         });
-        if (grant_type !== "authorization_code") {
+        if (grant_type !== "authorization_code" && grant_type !== "refresh_token") {
             logger.warn("[MCP OAuth] Token rejected: unsupported grant_type", {
                 grant_type: grant_type ?? null,
             });
             return res.status(400).json({
                 error: "unsupported_grant_type",
-                error_description: "Only authorization_code is supported",
+                error_description: "Only authorization_code and refresh_token are supported",
             });
         }
+        if (grant_type === "refresh_token") {
+            if (!refresh_token || typeof refresh_token !== "string") {
+                logger.warn("[MCP OAuth] Token refresh rejected: missing refresh_token");
+                return res
+                    .status(400)
+                    .json({ error: "invalid_request", error_description: "refresh_token is required" });
+            }
+            const { refreshAccessToken } = await import("./services/mcp_oauth.js");
+            const token = await refreshAccessToken(refresh_token);
+            logger.info("[MCP OAuth] Token refreshed", {
+                has_refresh_token: Boolean(token.refresh_token),
+            });
+            res.setHeader("Content-Type", "application/json");
+            return res.json(token);
+        }
         if (!code || typeof code !== "string") {
             logger.warn("[MCP OAuth] Token rejected: missing code");
             return res
@@ -3271,6 +3289,21 @@ app.get("/agents/:key/records", async (req, res) => {
         return handleApiError(req, res, error, "Failed to list agent records", "DB_QUERY_FAILED", "APIError:agents_records");
     }
 });
+// GET /recent_conversations/:conversation_id — Inspector: one conversation with nested messages
+app.get("/recent_conversations/:conversation_id", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const conversationId = String(req.params.conversation_id ?? "").trim();
+        const item = getRecentConversationById(userId, conversationId);
+        if (!item) {
+            return sendError(res, 404, "RESOURCE_NOT_FOUND", "Conversation not found");
+        }
+        return res.json(item);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to load conversation", "DB_QUERY_FAILED", "APIError:recent_conversation_detail");
+    }
+});
 // GET /recent_conversations — Inspector: conversations with nested messages (SQLite)
 app.get("/recent_conversations", async (req, res) => {
     try {
@@ -3279,7 +3312,9 @@ app.get("/recent_conversations", async (req, res) => {
         const offset = parseInt(String(req.query.offset ?? "0"), 10) || 0;
         const activity_after = typeof req.query.activity_after === "string" ? req.query.activity_after.trim() || null : null;
         const activity_before = typeof req.query.activity_before === "string" ? req.query.activity_before.trim() || null : null;
-        const agent_key = typeof req.query.agent_key === "string" ? req.query.agent_key.trim() || null : null;
+        const agentKeyRaw = typeof req.query.agent_key === "string" ? req.query.agent_key.trim() : "";
+        // UI and bookmarks may send agent_key=all; never treat that as a real deriveAgentKey value.
+        const agent_key = agentKeyRaw.length > 0 && agentKeyRaw.toLowerCase() !== "all" ? agentKeyRaw : null;
         const result = listRecentConversations(userId, limit, offset, {
             activity_after,
             activity_before,
@@ -3328,6 +3363,32 @@ app.get("/turns/:turn_key", async (req, res) => {
         return handleApiError(req, res, error, "Failed to get turn", "DB_QUERY_FAILED", "APIError:turn_detail");
     }
 });
+// GET /admin/compliance/scorecard — Inspector: aggregated hook compliance (SQLite)
+app.get("/admin/compliance/scorecard", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const since = typeof req.query.since === "string" ? req.query.since : undefined;
+        const until = typeof req.query.until === "string" ? req.query.until : undefined;
+        const group_by = typeof req.query.group_by === "string" ? req.query.group_by : undefined;
+        const min_turns = parseInt(String(req.query.min_turns ?? ""), 10);
+        const min_backfill_rate = parseFloat(String(req.query.min_backfill_rate ?? ""));
+        const top_missed_steps = parseInt(String(req.query.top_missed_steps ?? ""), 10);
+        const include_synthetic = req.query.include_synthetic === "1" || String(req.query.include_synthetic).toLowerCase() === "true";
+        const result = buildComplianceScorecard(userId, {
+            since,
+            until,
+            group_by,
+            min_turns: Number.isFinite(min_turns) ? min_turns : undefined,
+            min_backfill_rate: Number.isFinite(min_backfill_rate) ? min_backfill_rate : undefined,
+            top_missed_steps: Number.isFinite(top_missed_steps) ? top_missed_steps : undefined,
+            include_synthetic,
+        });
+        return res.json(result);
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to build compliance scorecard", "DB_QUERY_FAILED", "APIError:compliance_scorecard");
+    }
+});
 // GET /api/sources - Get source list (FU-301)
 app.get("/sources", async (req, res) => {
     try {
@@ -4185,30 +4246,41 @@ export async function storeStructuredForApi(params) {
     if (commit && relationships && relationships.length > 0) {
         const { relationshipsService } = await import("./services/relationships.js");
         for (const rel of relationships) {
-            const source = resolved[rel.source_index];
-            const target = resolved[rel.target_index];
-            if (!source || !target) {
-                logger.warn(`[STORE] Skipping relationship: invalid source_index=${rel.source_index} ` +
-                    `or target_index=${rel.target_index} (have ${resolved.length} entities).`);
+            const sourceEntityId = typeof rel.source_entity_id === "string"
+                ? rel.source_entity_id
+                : typeof rel.source_index === "number"
+                    ? resolved[rel.source_index]?.entity_id
+                    : undefined;
+            const targetEntityId = typeof rel.target_entity_id === "string"
+                ? rel.target_entity_id
+                : typeof rel.target_index === "number"
+                    ? resolved[rel.target_index]?.entity_id
+                    : undefined;
+            if (!sourceEntityId || !targetEntityId) {
+                logger.warn(`[STORE] Skipping relationship: invalid source reference ` +
+                    `(source_index=${rel.source_index}, source_entity_id=${rel.source_entity_id}) ` +
+                    `or target reference (target_index=${rel.target_index}, ` +
+                    `target_entity_id=${rel.target_entity_id}); have ${resolved.length} entities.`);
                 continue;
             }
             try {
                 await relationshipsService.createRelationship({
-                    source_entity_id: source.entity_id,
-                    target_entity_id: target.entity_id,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
                     relationship_type: rel.relationship_type,
                     source_id: storageResult.sourceId,
+                    metadata: rel.metadata ?? {},
                     user_id: userId,
                 });
                 relationshipsCreated.push({
                     relationship_type: rel.relationship_type,
-                    source_entity_id: source.entity_id,
-                    target_entity_id: target.entity_id,
+                    source_entity_id: sourceEntityId,
+                    target_entity_id: targetEntityId,
                 });
             }
             catch (relErr) {
                 logger.warn(`Failed to create relationship ${rel.relationship_type} ` +
-                    `${source.entity_id} -> ${target.entity_id}: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
+                    `${sourceEntityId} -> ${targetEntityId}: ${relErr instanceof Error ? relErr.message : String(relErr)}`);
             }
         }
     }
@@ -4776,6 +4848,63 @@ app.post("/create_relationship", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", error instanceof Error ? error.message : "Failed to create relationship");
     }
 });
+// Create relationships in batch
+app.post("/create_relationships", async (req, res) => {
+    const parsed = CreateRelationshipsRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+        logWarn("ValidationError:create_relationships", req, {
+            issues: parsed.error.issues,
+        });
+        return sendValidationError(res, parsed.error.issues);
+    }
+    const { relationships, source_id, user_id } = parsed.data;
+    const { relationshipsService } = await import("./services/relationships.js");
+    try {
+        const userId = await getAuthenticatedUserId(req, user_id);
+        const created = [];
+        const errors = [];
+        for (const [index, relationship] of relationships.entries()) {
+            try {
+                const snapshot = await relationshipsService.createRelationship({
+                    relationship_type: relationship.relationship_type,
+                    source_entity_id: relationship.source_entity_id,
+                    target_entity_id: relationship.target_entity_id,
+                    source_id: relationship.source_id || source_id || null,
+                    metadata: relationship.metadata || {},
+                    user_id: userId,
+                });
+                created.push({
+                    index,
+                    ...snapshot,
+                });
+            }
+            catch (error) {
+                errors.push({
+                    index,
+                    relationship,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        logDebug("Success:create_relationships", req, {
+            requested: relationships.length,
+            created: created.length,
+            errors: errors.length,
+        });
+        return res.json({
+            success: errors.length === 0,
+            requested: relationships.length,
+            created_count: created.length,
+            error_count: errors.length,
+            relationships: created,
+            errors,
+        });
+    }
+    catch (error) {
+        logError("RelationshipCreationError:create_relationships", req, error);
+        return sendError(res, 500, "DB_QUERY_FAILED", error instanceof Error ? error.message : "Failed to create relationships");
+    }
+});
 // List relationships
 app.post("/list_relationships", async (req, res) => {
     const parsed = ListRelationshipsRequestSchema.safeParse(req.body);