@starascendin/lifeos-mcp 0.7.67 → 0.7.69

package/README.md

@@ -24,17 +24,20 @@ npx @starascendin/lifeos-mcp --url <your-convex-url> --user-id <your-user-id> --
 | User ID | `--user-id`, `-i` | `LIFEOS_USER_ID` | Your LifeOS user ID |
 | API Key | `--api-key`, `-k` | `LIFEOS_API_KEY` | Your API key for authentication |
 
-### Optional SurrealDB Sidecar Parameters
+### Optional FalkorDB Sidecar Parameters
 
-These are required only for the Surreal graph tools.
+These are required only for the Falkor graph tools.
 
 | Env Variable | Description |
 |--------------|-------------|
-| `SURREAL_ENDPOINT` | SurrealDB HTTP endpoint, e.g. `https://surrealdbprod.apps.rjlabs.dev` |
-| `SURREAL_USER` | SurrealDB username |
-| `SURREAL_PASS` | SurrealDB password |
-| `SURREAL_NS` | Namespace, defaults to `lifeos` |
-| `SURREAL_DB` | Database, defaults to `graph` |
+| `FALKOR_BROWSER_ENDPOINT` | FalkorDB Browser HTTP endpoint, defaults to `https://falkordb.apps.rjlabs.dev` |
+| `FALKOR_GRAPH` | Falkor graph name, defaults to `lifeos_ppv` |
+| `FALKOR_PASS` | Falkor password, used to mint short-lived browser tokens |
+| `FALKOR_TOKEN` / `FALKOR_PAT` | Optional pre-provisioned Falkor browser token |
+| `FALKOR_USER` | Falkor username, defaults to `default` |
+| `FALKOR_HOST` | Browser backend Redis host, defaults to `localhost` |
+| `FALKOR_PORT` | Browser backend Redis port, defaults to `6379` |
+| `FALKOR_TLS` | Browser backend Redis TLS flag, defaults to `false` |
 
 ### Getting Your Credentials
 
@@ -190,16 +193,16 @@ Add to your `.mcp.json` (project root or `~/.claude/mcp.json`):
 - **refresh_unified_graph_cache** - Recompute inferred graph links and refresh the cached projection
 - **upsert_unified_graph_link / delete_unified_graph_link** - Create or remove manual links between graph nodes
 
-### SurrealDB Sidecar Graph
-- **surreal_graph_schema** - Inspect the agent graph contract, configured namespace/db, allowed table prefixes, relation tables, and examples
-- **surreal_graph_query** - Run guarded read-only SurrealQL (`SELECT`, `INFO`, `EXPLAIN` only)
-- **surreal_graph_link** - Create/update an agent-owned relationship in `lifeos_agent_links` without mutating Convex-synced entity tables
-- **surreal_graph_unlink** - Remove a relationship previously created by `surreal_graph_link`
+### FalkorDB Sidecar Graph
+- **falkor_graph_schema** - Inspect the Falkor graph contract, configured graph, allowed labels, relationship types, and examples
+- **falkor_graph_query** - Run guarded read-only Cypher against the Falkor PPV sidecar
+- **falkor_graph_link** - Create/update an agent-owned `AGENT_LINK` relationship without mutating Convex-synced nodes or inferred PPV relationships
+- **falkor_graph_unlink** - Remove a relationship previously created by `falkor_graph_link`
 
-Surreal graph rules:
+Falkor graph rules:
 - Convex remains canonical for entity data.
-- SurrealDB is the relationship/query sidecar.
-- Agents may query graph data and write only agent-owned links through `lifeos_agent_links`.
+- FalkorDB is a graph query/read sidecar for the PPV experiment.
+- Agents may query graph data and write only agent-owned `AGENT_LINK` relationships.
 - Every agent-created link must include a reason and confidence.
 - Raw read queries should include `LIMIT`.
 

package/dist/build-info.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.7.67";
-export declare const BUILD_TIME = "2026-05-17T16:11:21.616Z";
+export declare const VERSION = "0.7.69";
+export declare const BUILD_TIME = "2026-05-17T20:11:00.340Z";

package/dist/build-info.js

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Regenerated on every build.
-export const VERSION = "0.7.67";
-export const BUILD_TIME = "2026-05-17T16:11:21.616Z";
+export const VERSION = "0.7.69";
+export const BUILD_TIME = "2026-05-17T20:11:00.340Z";

package/dist/index.js

@@ -60,7 +60,7 @@ program
 });
 program
     .command("ppv <action>")
-    .description("Manage PPV as JSON. Actions: workspace, graph, vision-graph, seed, vision, activate-vision, set-active-vision, identity, pillar, action, reflection, adjustment.")
+    .description("Manage PPV as JSON. Actions: workspace, graph, vision-graph, seed, vision, activate-vision, set-active-vision, identity, pillar.")
     .option("--file <file>", "JSON payload file for mutating actions. workspace, graph, vision-graph, and seed do not require a file.")
     .action((action, commandOptions) => {
     directCliCommand = {
@@ -685,6 +685,19 @@ const TOOLS = [
                     type: "string",
                     description: "Updated goals (optional)",
                 },
+                whatWentWell: {
+                    type: "string",
+                    description: "Retrospective notes on what went well (optional)",
+                },
+                whatCouldImprove: {
+                    type: "string",
+                    description: "Retrospective notes on what could improve (optional)",
+                },
+                actionItems: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Retrospective action items (optional)",
+                },
             },
             required: ["cycleId"],
         },
@@ -4542,7 +4555,7 @@ const TOOLS = [
     // PPV v1 tools
     {
         name: "get_ppv_workspace",
-        description: "Get the PPV workspace for the selected vision, plus all owned visions, active-vision context, identity, pillars, linked projects, weekly actions, reflections, and adjustments.",
+        description: "Get the PPV workspace for the selected vision, plus all owned visions, active-vision context, identity, pillars, and linked projects.",
         inputSchema: {
             type: "object",
             properties: {
@@ -4553,7 +4566,7 @@ const TOOLS = [
     },
     {
         name: "get_active_vision_graph",
-        description: "Best default graph read for PPV questions. Get the unified active-vision graph linking PPV vision, identity, pillars, weekly actions, reflections, adjustments, related projects/issues, and recent voice memos.",
+        description: "Best default graph read for PPV questions. Get the unified active-vision graph linking PPV vision, identity, pillars, related projects/issues, and recent voice memos.",
         inputSchema: {
             type: "object",
             properties: {
@@ -4730,52 +4743,52 @@ const TOOLS = [
         },
     },
     {
-        name: "surreal_graph_schema",
-        description: "Inspect the SurrealDB sidecar graph contract for agents: connection state, allowed node-table prefixes, safe query rules, relation tables, and example SurrealQL. Use before raw SurrealQL graph work.",
+        name: "falkor_graph_schema",
+        description: "Inspect the FalkorDB sidecar graph contract for agents: configured graph, mirrored PPV labels, safe Cypher rules, relationship types, and examples. Use before raw Falkor Cypher graph work.",
         inputSchema: {
             type: "object",
             properties: {},
         },
     },
     {
-        name: "surreal_graph_query",
-        description: "Run guarded read-only SurrealQL against the LifeOS SurrealDB graph sidecar. Allowed statements are SELECT, INFO, and EXPLAIN only. Use LIMIT for SELECT queries. Do not use this for Convex-canonical writes.",
+        name: "falkor_graph_query",
+        description: "Run guarded read-only Cypher against the LifeOS FalkorDB graph sidecar. Allowed statements are MATCH, WITH, RETURN, EXPLAIN, and PROFILE query shapes only. MATCH queries should include LIMIT unless doing count aggregation. Do not use this for Convex-canonical writes.",
         inputSchema: {
             type: "object",
             properties: {
                 query: {
                     type: "string",
-                    description: "Read-only SurrealQL. SELECT statements must include LIMIT unless they are aggregate count queries.",
+                    description: "Read-only Cypher. MATCH queries should include LIMIT unless they are aggregate count queries.",
                 },
                 maxRows: {
                     type: "number",
-                    description: "Maximum rows returned per statement result after execution. Default 50, max 200.",
+                    description: "Maximum rows returned after execution. Default 50, max 200.",
                 },
             },
             required: ["query"],
         },
     },
     {
-        name: "surreal_graph_link",
-        description: "Create or update an agent-owned graph relationship in SurrealDB between two LifeOS records. This writes only to the lifeos_agent_links relation table and never mutates Convex-synced entity records.",
+        name: "falkor_graph_link",
+        description: "Create or update an agent-owned AGENT_LINK relationship in FalkorDB between two existing LifeOS graph records. This never mutates Convex-synced nodes or inferred PPV relationships.",
         inputSchema: {
             type: "object",
             properties: {
-                fromTable: {
+                fromLabel: {
                     type: "string",
-                    description: "Source Surreal table, e.g. ppv1_pillars or lifeos_pmProjects.",
+                    description: "Source Falkor node label, e.g. PpvPillar.",
                 },
                 fromId: {
                     type: "string",
-                    description: "Source record id without the table prefix.",
+                    description: "Source Convex record id stored in node.convexId.",
                 },
-                toTable: {
+                toLabel: {
                     type: "string",
-                    description: "Target Surreal table, e.g. lifeos_pmProjects or lifeos_frmPeople.",
+                    description: "Target Falkor node label, e.g. PpvProject.",
                 },
                 toId: {
                     type: "string",
-                    description: "Target record id without the table prefix.",
+                    description: "Target Convex record id stored in node.convexId.",
                 },
                 kind: {
                     type: "string",
@@ -4799,31 +4812,31 @@ const TOOLS = [
                     additionalProperties: true,
                 },
             },
-            required: ["fromTable", "fromId", "toTable", "toId", "kind", "reason"],
+            required: ["fromLabel", "fromId", "toLabel", "toId", "kind", "reason"],
         },
     },
     {
-        name: "surreal_graph_unlink",
-        description: "Remove an agent-owned SurrealDB graph relationship previously created by surreal_graph_link. This only deletes from lifeos_agent_links.",
+        name: "falkor_graph_unlink",
+        description: "Remove an agent-owned FalkorDB AGENT_LINK relationship previously created by falkor_graph_link.",
         inputSchema: {
             type: "object",
             properties: {
-                fromTable: { type: "string", description: "Source Surreal table." },
+                fromLabel: { type: "string", description: "Source Falkor node label." },
                 fromId: {
                     type: "string",
-                    description: "Source record id without table prefix.",
+                    description: "Source Convex record id stored in node.convexId.",
                 },
-                toTable: { type: "string", description: "Target Surreal table." },
+                toLabel: { type: "string", description: "Target Falkor node label." },
                 toId: {
                     type: "string",
-                    description: "Target record id without table prefix.",
+                    description: "Target Convex record id stored in node.convexId.",
                 },
                 kind: {
                     type: "string",
                     description: "Relationship kind used when linking.",
                 },
             },
-            required: ["fromTable", "fromId", "toTable", "toId", "kind"],
+            required: ["fromLabel", "fromId", "toLabel", "toId", "kind"],
         },
     },
     {
@@ -4914,7 +4927,7 @@ const TOOLS = [
     },
     {
         name: "delete_ppv_vision",
-        description: "Delete a PPV vision and cascade-delete its identity, pillars, weekly actions, reflections, and adjustments.",
+        description: "Delete a PPV vision and cascade-delete its identity and pillars.",
         inputSchema: {
             type: "object",
             properties: {
@@ -5017,143 +5030,6 @@ const TOOLS = [
             required: ["pillarId"],
         },
     },
-    {
-        name: "create_ppv_weekly_action",
-        description: "Create an identity-aligned PPV weekly action.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                visionId: { type: "string", description: "PPV vision ID" },
-                pillarId: { type: "string", description: "PPV pillar ID" },
-                projectId: {
-                    type: "string",
-                    description: "Existing LifeOS project ID",
-                },
-                category: { type: "string", description: "Action category" },
-                action: { type: "string", description: "Small action to take" },
-                status: {
-                    type: "string",
-                    enum: ["pending", "in_progress", "completed", "skipped"],
-                    description: "Action status",
-                },
-                scheduledDate: { type: "string", description: "ISO scheduled date" },
-                week: { type: "string", description: "ISO week label" },
-            },
-            required: ["visionId", "category", "action"],
-        },
-    },
-    {
-        name: "update_ppv_weekly_action",
-        description: "Update a PPV weekly action.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                actionId: { type: "string", description: "PPV weekly action ID" },
-                pillarId: { type: "string", description: "PPV pillar ID" },
-                projectId: {
-                    type: "string",
-                    description: "Existing LifeOS project ID",
-                },
-                category: { type: "string", description: "Updated category" },
-                action: { type: "string", description: "Updated action" },
-                status: {
-                    type: "string",
-                    enum: ["pending", "in_progress", "completed", "skipped"],
-                    description: "Updated status",
-                },
-                scheduledDate: { type: "string", description: "ISO scheduled date" },
-                week: { type: "string", description: "ISO week label" },
-            },
-            required: ["actionId"],
-        },
-    },
-    {
-        name: "delete_ppv_weekly_action",
-        description: "Delete a PPV weekly action.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                actionId: { type: "string", description: "PPV weekly action ID" },
-            },
-            required: ["actionId"],
-        },
-    },
-    {
-        name: "create_ppv_reflection",
-        description: "Create a PPV weekly reflection.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                visionId: { type: "string", description: "PPV vision ID" },
-                week: { type: "string", description: "ISO week label" },
-                questions: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            question: { type: "string" },
-                            answer: { type: "string" },
-                        },
-                        required: ["question", "answer"],
-                    },
-                    description: "Reflection questions and answers",
-                },
-                alignmentScore: { type: "number", description: "Optional score" },
-            },
-            required: ["visionId", "week", "questions"],
-        },
-    },
-    {
-        name: "delete_ppv_reflection",
-        description: "Delete a PPV reflection.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                reflectionId: { type: "string", description: "PPV reflection ID" },
-            },
-            required: ["reflectionId"],
-        },
-    },
-    {
-        name: "create_ppv_adjustment",
-        description: "Create a PPV adjustment from reflection or lived evidence.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                visionId: { type: "string", description: "PPV vision ID" },
-                sourceReflectionId: {
-                    type: "string",
-                    description: "Source PPV reflection ID",
-                },
-                observation: { type: "string", description: "What was observed" },
-                decision: { type: "string", description: "What will change" },
-                affectedComponents: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Components affected by the adjustment",
-                },
-            },
-            required: ["visionId", "observation", "decision", "affectedComponents"],
-        },
-    },
-    {
-        name: "delete_ppv_adjustment",
-        description: "Delete a PPV adjustment.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Override user ID" },
-                adjustmentId: { type: "string", description: "PPV adjustment ID" },
-            },
-            required: ["adjustmentId"],
-        },
-    },
     // MCP Server Info
     {
         name: "get_version",
@@ -5233,22 +5109,22 @@ const PROMPTS = [
     },
     {
         name: "ppv",
-        description: "Manage the PPV life design system: vision, identity, pillars, projects, weekly actions, reflections, and adjustments.",
+        description: "Manage the PPV life design system: vision, identity, pillars, and projects.",
         arguments: [
             {
                 name: "intent",
-                description: "What to do with PPV, e.g. create vision, add weekly action, reflect, adjust, link project.",
+                description: "What to do with PPV, e.g. create vision, update identity, add pillar, link project.",
                 required: false,
             },
         ],
     },
     {
-        name: "surreal-graph",
-        description: "Use the SurrealDB sidecar graph: query LifeOS graph relationships with SurrealQL and create controlled agent-owned graph links.",
+        name: "falkor-graph",
+        description: "Use the FalkorDB sidecar graph: query PPV graph relationships with Cypher and create controlled agent-owned graph links.",
         arguments: [
             {
                 name: "intent",
-                description: "What to do with the Surreal graph, e.g. inspect PPV-project links, connect a chat to a project, or find related people.",
+                description: "What to do with the Falkor graph, e.g. inspect PPV-project links or add an agent-owned PPV relationship.",
                 required: false,
             },
         ],
@@ -5614,7 +5490,7 @@ Do not ask for confirmation; the user intends this planning workflow to mutate L
 ${intentClause}
 
 Use the LifeOS MCP PPV tools:
-1. Call get_ppv_workspace first to inspect all owned visions, the selected/current vision, identity, pillars, linked projects, weekly actions, reflections, adjustments, and available LifeOS projects.
+1. Call get_ppv_workspace first to inspect all owned visions, the selected/current vision, identity, pillars, linked projects, and available LifeOS projects.
 2. If there is no vision and the user wants the example, call seed_ppv_beijing_workspace.
 3. For vision changes, call upsert_ppv_vision.
 4. If the user wants to change a vision lifecycle without editing content, call set_ppv_vision_status.
@@ -5623,8 +5499,6 @@ Use the LifeOS MCP PPV tools:
 7. If the user wants to permanently remove a vision and its PPV subcomponents, call delete_ppv_vision.
 8. For identity work, call upsert_ppv_identity.
 9. For pillars, call create_ppv_pillar or update_ppv_pillar. Link only existing LifeOS project IDs from get_ppv_workspace.projects.
-10. For execution, call create_ppv_weekly_action or update_ppv_weekly_action.
-11. For learning loops, call create_ppv_reflection and create_ppv_adjustment.
 
 Keep the system simple:
 - Vision is directional and experiential, not a task list.
@@ -5632,38 +5506,37 @@ Keep the system simple:
 - Pillars are ongoing systems.
 - Projects are existing LifeOS projects.
 - Weekly actions should be small, concrete, and identity-aligned.
-- Reflections and adjustments should update behavior based on evidence.
 
 After mutating, report exactly what changed and any IDs needed for future updates.`,
                 },
             },
         ];
     },
-    "surreal-graph": (args) => {
+    "falkor-graph": (args) => {
         const intentClause = args.intent
             ? `User intent: ${args.intent}`
-            : "Start by inspecting the Surreal graph schema and current agent links.";
+            : "Start by inspecting the Falkor graph schema and current agent links.";
         return [
             {
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Use the LifeOS SurrealDB sidecar graph.
+                    text: `Use the LifeOS FalkorDB sidecar graph.
 
 ${intentClause}
 
 Use these MCP tools:
-1. Call surreal_graph_schema first to inspect the allowed graph contract and examples.
-2. Use surreal_graph_query for read-only SurrealQL. Only SELECT, INFO, and EXPLAIN are allowed; SELECT queries must include LIMIT unless doing count aggregation.
-3. Use surreal_graph_link when you need to create a relationship between existing LifeOS records. This writes only to lifeos_agent_links.
-4. Use surreal_graph_unlink only to remove relationships previously created by surreal_graph_link.
+1. Call falkor_graph_schema first to inspect the allowed graph contract and examples.
+2. Use falkor_graph_query for read-only Cypher. MATCH/WITH queries must include LIMIT unless doing count aggregation.
+3. Use falkor_graph_link when you need to create a relationship between existing Falkor nodes. This writes only AGENT_LINK relationships.
+4. Use falkor_graph_unlink only to remove relationships previously created by falkor_graph_link.
 
 Rules:
-- Convex remains canonical for entity data. Do not use SurrealDB to edit projects, PPV records, CRM people, chats, or notes.
-- SurrealDB is the graph memory / relationship layer.
+- Convex remains canonical for entity data. Do not use FalkorDB to edit projects or PPV records.
+- FalkorDB is the graph sidecar.
 - Always include a concrete reason and confidence when linking.
-- Prefer precise ids from prior reads; do not invent ids.
-- Keep queries scoped with LIMIT and return concise findings plus the SurrealQL you used when useful.`,
+- Prefer precise node labels and convexId values from prior reads; do not invent ids.
+- Keep queries scoped with LIMIT and return concise findings plus the Cypher you used when useful.`,
                 },
             },
         ];
@@ -6550,11 +6423,14 @@ Keep it concise and direct. This is an accountability report, not a feel-good su
 const CONVEX_URL = options.url || process.env.CONVEX_URL;
 const API_KEY = options.apiKey || process.env.LIFEOS_API_KEY;
 const USER_ID = options.userId || process.env.LIFEOS_USER_ID;
-const SURREAL_ENDPOINT = process.env.SURREAL_ENDPOINT;
-const SURREAL_USER = process.env.SURREAL_USER;
-const SURREAL_PASS = process.env.SURREAL_PASS;
-const SURREAL_NS = process.env.SURREAL_NS || "lifeos";
-const SURREAL_DB = process.env.SURREAL_DB || "graph";
+const FALKOR_BROWSER_ENDPOINT = process.env.FALKOR_BROWSER_ENDPOINT || "https://falkordb.apps.rjlabs.dev";
+const FALKOR_GRAPH = process.env.FALKOR_GRAPH || "lifeos_ppv";
+const FALKOR_USER = process.env.FALKOR_USER || "default";
+const FALKOR_PASS = process.env.FALKOR_PASS;
+const FALKOR_TOKEN = process.env.FALKOR_TOKEN || process.env.FALKOR_PAT;
+const FALKOR_HOST = process.env.FALKOR_HOST || "localhost";
+const FALKOR_PORT = process.env.FALKOR_PORT || "6379";
+const FALKOR_TLS = process.env.FALKOR_TLS || "false";
 // Validate required configuration
 const missingConfig = [];
 if (!CONVEX_URL)
@@ -6666,13 +6542,6 @@ async function runDirectCliCommand(command) {
             pillar: "create_ppv_pillar",
             "update-pillar": "update_ppv_pillar",
             "delete-pillar": "delete_ppv_pillar",
-            action: "create_ppv_weekly_action",
-            "update-action": "update_ppv_weekly_action",
-            "delete-action": "delete_ppv_weekly_action",
-            reflection: "create_ppv_reflection",
-            "delete-reflection": "delete_ppv_reflection",
-            adjustment: "create_ppv_adjustment",
-            "delete-adjustment": "delete_ppv_adjustment",
         };
         const tool = actionToTool[command.action];
         if (!tool) {
@@ -6708,55 +6577,6 @@ async function callConvexJsonEndpoint(path, body) {
     }
     return await response.json();
 }
-const SURREAL_AGENT_LINK_TABLE = "lifeos_agent_links";
-const SURREAL_TABLE_PREFIXES = ["lifeos_", "life_", "ppv1_"];
-const SURREAL_RELATION_TABLES = [
-    "ppv_has_identity",
-    "ppv_has_pillar",
-    "ppv_has_action",
-    "ppv_has_reflection",
-    "ppv_has_adjustment",
-    "ppv_pillar_drives_action",
-    "ppv_pillar_supports_project",
-    "ppv_project_executes_action",
-    "ppv_reflection_inspires_adjustment",
-    SURREAL_AGENT_LINK_TABLE,
-];
-const SURREAL_MUTATING_KEYWORDS = [
-    "ALTER",
-    "CREATE",
-    "DEFINE",
-    "DELETE",
-    "INSERT",
-    "KILL",
-    "LIVE",
-    "REBUILD",
-    "RELATE",
-    "REMOVE",
-    "SLEEP",
-    "THROW",
-    "UPDATE",
-    "UPSERT",
-];
-function requireSurrealConfig() {
-    const missing = [];
-    if (!SURREAL_ENDPOINT)
-        missing.push("SURREAL_ENDPOINT");
-    if (!SURREAL_USER)
-        missing.push("SURREAL_USER");
-    if (!SURREAL_PASS)
-        missing.push("SURREAL_PASS");
-    if (missing.length > 0) {
-        throw new Error(`Missing SurrealDB configuration: ${missing.join(", ")}. Set SURREAL_ENDPOINT, SURREAL_USER, SURREAL_PASS, SURREAL_NS, and SURREAL_DB in the agent runtime.`);
-    }
-    return {
-        endpoint: SURREAL_ENDPOINT,
-        user: SURREAL_USER,
-        pass: SURREAL_PASS,
-        ns: SURREAL_NS,
-        db: SURREAL_DB,
-    };
-}
 function stripSqlCommentsAndStrings(sql) {
     let output = "";
     let index = 0;
@@ -6809,74 +6629,11 @@ function stripSqlCommentsAndStrings(sql) {
     }
     return output;
 }
-function splitSqlStatements(sql) {
-    return stripSqlCommentsAndStrings(sql)
-        .split(";")
-        .map((statement) => statement.trim())
-        .filter(Boolean);
-}
-function assertReadOnlySurrealSql(sql) {
-    const statements = splitSqlStatements(sql);
-    if (statements.length === 0) {
-        throw new Error("SurrealQL query is empty.");
-    }
-    if (statements.length > 5) {
-        throw new Error("SurrealQL query is too broad. Use 5 statements or fewer.");
-    }
-    for (const statement of statements) {
-        const upper = statement.toUpperCase();
-        const startsReadOnly = upper.startsWith("SELECT ") ||
-            upper.startsWith("INFO ") ||
-            upper.startsWith("EXPLAIN ");
-        if (!startsReadOnly) {
-            throw new Error("surreal_graph_query only allows SELECT, INFO, and EXPLAIN statements. Use surreal_graph_link for controlled relationship writes.");
-        }
-        for (const keyword of SURREAL_MUTATING_KEYWORDS) {
-            if (new RegExp(`\\b${keyword}\\b`, "i").test(statement)) {
-                throw new Error(`surreal_graph_query blocked mutating keyword ${keyword}. Use guarded graph write tools instead.`);
-            }
-        }
-        const isAggregateCount = /\bCOUNT\s*\(/i.test(statement);
-        if (upper.startsWith("SELECT ") &&
-            !/\bLIMIT\b/i.test(statement) &&
-            !isAggregateCount) {
-            throw new Error("SELECT queries must include LIMIT unless they are aggregate count queries.");
-        }
-    }
-}
 function clampMaxRows(value) {
     if (typeof value !== "number" || !Number.isFinite(value))
         return 50;
     return Math.max(1, Math.min(200, Math.floor(value)));
 }
-function capSurrealResults(results, maxRows) {
-    return results.map((entry) => {
-        if (!Array.isArray(entry.result) || entry.result.length <= maxRows) {
-            return entry;
-        }
-        return {
-            ...entry,
-            result: entry.result.slice(0, maxRows),
-            detail: `${entry.result.length - maxRows} additional rows omitted by lifeos-mcp maxRows=${maxRows}`,
-        };
-    });
-}
-function assertSurrealIdentifier(value, label) {
-    if (typeof value !== "string" || !/^[A-Za-z][A-Za-z0-9_]*$/.test(value)) {
-        throw new Error(`${label} must be a simple Surreal identifier.`);
-    }
-    return value;
-}
-function assertLifeOsNodeTable(value, label) {
-    const table = assertSurrealIdentifier(value, label);
-    if (!SURREAL_TABLE_PREFIXES.some((prefix) => table.startsWith(prefix))) {
-        throw new Error(`${label} must start with one of: ${SURREAL_TABLE_PREFIXES.join(", ")}`);
-    }
-    if (SURREAL_RELATION_TABLES.includes(table)) {
-        throw new Error(`${label} must be an entity table, not a relation table.`);
-    }
-    return table;
-}
 function assertRecordId(value, label) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new Error(`${label} is required.`);
@@ -6892,79 +6649,237 @@ function assertRelationKind(value) {
     }
     return value;
 }
-function escapeSurrealRecordId(id) {
-    return id.replace(/`/g, "\\`");
+const FALKOR_AGENT_RELATIONSHIP = "AGENT_LINK";
+const FALKOR_NODE_LABELS = [
+    "PpvVision",
+    "PpvIdentity",
+    "PpvPillar",
+    "PpvProject",
+];
+const FALKOR_INFERRED_RELATIONSHIPS = [
+    "HAS_IDENTITY",
+    "HAS_PILLAR",
+    "PILLAR_SUPPORTS_PROJECT",
+];
+const FALKOR_MUTATING_KEYWORDS = [
+    "CALL",
+    "CREATE",
+    "DELETE",
+    "DROP",
+    "FOREACH",
+    "LOAD",
+    "MERGE",
+    "REMOVE",
+    "SET",
+];
+function requireFalkorConfig() {
+    if (!FALKOR_TOKEN && !FALKOR_PASS) {
+        throw new Error("Missing FalkorDB configuration: set FALKOR_TOKEN/FALKOR_PAT or FALKOR_PASS in the agent runtime.");
+    }
+    return {
+        endpoint: FALKOR_BROWSER_ENDPOINT,
+        graph: FALKOR_GRAPH,
+        username: FALKOR_USER,
+        password: FALKOR_PASS,
+        token: FALKOR_TOKEN,
+        host: FALKOR_HOST,
+        port: FALKOR_PORT,
+        tls: FALKOR_TLS,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function surrealThing(table, id) {
-    return `${table}:\`${escapeSurrealRecordId(id)}\``;
+function cypherString(value) {
+    return `'${String(value).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 }
-function agentLinkId(parts) {
-    return [parts.kind, parts.fromTable, parts.fromId, parts.toTable, parts.toId]
-        .join("__")
-        .replace(/[^A-Za-z0-9_:-]/g, "_")
-        .slice(0, 512);
+function cypherValue(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "NULL";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return cypherString(value);
+    if (Array.isArray(value))
+        return `[${value.map(cypherValue).join(", ")}]`;
+    return cypherString(JSON.stringify(value));
+}
+function cypherProps(props) {
+    return `{${Object.entries(props)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}: ${cypherValue(value)}`)
+        .join(", ")}}`;
 }
-async function runSurrealSql(sql) {
-    const cfg = requireSurrealConfig();
-    const credentials = Buffer.from(`${cfg.user}:${cfg.pass}`).toString("base64");
-    const response = await fetch(`${cfg.endpoint.replace(/\/$/, "")}/sql`, {
+async function requestFalkorToken(config, attempt) {
+    if (!config.password) {
+        throw new Error("FALKOR_PASS is required when FALKOR_TOKEN is not set.");
+    }
+    const tokenName = [
+        "lifeos-mcp",
+        attempt === 0 ? "graph" : "retry",
+        Date.now(),
+        Math.random().toString(36).slice(2, 10),
+    ].join("-");
+    const response = await fetch(`${config.endpoint.replace(/\/$/, "")}/api/auth/tokens/credentials`, {
         method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            username: config.username,
+            password: config.password,
+            host: config.host,
+            port: config.port,
+            tls: config.tls,
+            name: tokenName,
+            ttlSeconds: 3600,
+        }),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`FalkorDB auth failed (${response.status}): ${text}`);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed.token) {
+        throw new Error(`FalkorDB auth returned no token: ${text}`);
+    }
+    return parsed.token;
+}
+async function getFalkorToken(config) {
+    if (config.token)
+        return config.token;
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            return await requestFalkorToken(config, attempt);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < 2)
+                await sleep(250 * (attempt + 1));
+        }
+    }
+    throw lastError;
+}
+function parseFalkorEventStream(text) {
+    const data = text
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n")
+        .trim();
+    if (!data)
+        return { data: [], metadata: [] };
+    return JSON.parse(data);
+}
+async function runFalkorQuery(query) {
+    const config = requireFalkorConfig();
+    const token = await getFalkorToken(config);
+    const url = `${config.endpoint.replace(/\/$/, "")}/api/graph/${encodeURIComponent(config.graph)}?query=${encodeURIComponent(query)}&timeout=30000`;
+    const response = await fetch(url, {
+        method: "GET",
         headers: {
-            Authorization: `Basic ${credentials}`,
-            "Content-Type": "text/plain",
-            Accept: "application/json",
-            "Surreal-NS": cfg.ns,
-            "Surreal-DB": cfg.db,
+            Authorization: `Bearer ${token}`,
+            Accept: "text/event-stream",
         },
-        body: sql,
     });
     const text = await response.text();
     if (!response.ok) {
-        throw new Error(`SurrealDB SQL failed (${response.status}): ${text}`);
+        throw new Error(`FalkorDB query failed (${response.status}): ${text}`);
     }
-    const parsed = JSON.parse(text);
-    const failed = parsed.find((entry) => entry.status !== "OK");
-    if (failed) {
-        throw new Error(`SurrealDB SQL failed: ${JSON.stringify(failed, null, 2)}`);
+    return parseFalkorEventStream(text);
+}
+function assertReadOnlyFalkorCypher(query) {
+    const stripped = stripSqlCommentsAndStrings(query).trim();
+    if (!stripped)
+        throw new Error("FalkorDB Cypher query is empty.");
+    if (stripped.includes(";")) {
+        throw new Error("falkor_graph_query allows one Cypher statement at a time.");
+    }
+    const upper = stripped.toUpperCase();
+    const startsReadOnly = upper.startsWith("MATCH ") ||
+        upper.startsWith("WITH ") ||
+        upper.startsWith("RETURN ") ||
+        upper.startsWith("EXPLAIN ") ||
+        upper.startsWith("PROFILE ");
+    if (!startsReadOnly) {
+        throw new Error("falkor_graph_query only allows read-only Cypher. Start with MATCH, WITH, RETURN, EXPLAIN, or PROFILE.");
+    }
+    for (const keyword of FALKOR_MUTATING_KEYWORDS) {
+        if (new RegExp(`\\b${keyword}\\b`, "i").test(stripped)) {
+            throw new Error(`falkor_graph_query blocked mutating keyword ${keyword}. Use falkor_graph_link for guarded relationship writes.`);
+        }
+    }
+    const isAggregateCount = /\bCOUNT\s*\(/i.test(stripped);
+    if ((upper.startsWith("MATCH ") || upper.startsWith("WITH ")) &&
+        !/\bLIMIT\b/i.test(stripped) &&
+        !isAggregateCount) {
+        throw new Error("MATCH/WITH queries must include LIMIT unless they are aggregate count queries.");
+    }
+}
+function capFalkorResult(result, maxRows) {
+    const rows = result.data ?? [];
+    if (rows.length <= maxRows)
+        return result;
+    return {
+        ...result,
+        data: rows.slice(0, maxRows),
+        detail: `${rows.length - maxRows} additional rows omitted by lifeos-mcp maxRows=${maxRows}`,
+    };
+}
+function assertFalkorIdentifier(value, label) {
+    if (typeof value !== "string" || !/^[A-Za-z][A-Za-z0-9_]*$/.test(value)) {
+        throw new Error(`${label} must be a simple Falkor identifier.`);
+    }
+    return value;
+}
+function assertFalkorLabel(value, label) {
+    const nodeLabel = assertFalkorIdentifier(value, label);
+    if (!FALKOR_NODE_LABELS.includes(nodeLabel)) {
+        throw new Error(`${label} must be one of: ${FALKOR_NODE_LABELS.join(", ")}`);
     }
-    return parsed;
+    return nodeLabel;
 }
-function surrealGraphSchema() {
+function falkorLinkId(parts) {
+    return [parts.kind, parts.fromLabel, parts.fromId, parts.toLabel, parts.toId]
+        .join("__")
+        .replace(/[^A-Za-z0-9_:-]/g, "_")
+        .slice(0, 512);
+}
+function falkorGraphSchema() {
     return {
-        configured: Boolean(SURREAL_ENDPOINT && SURREAL_USER && SURREAL_PASS),
-        endpointConfigured: Boolean(SURREAL_ENDPOINT),
-        namespace: SURREAL_NS,
-        database: SURREAL_DB,
-        nodeTablePrefixes: SURREAL_TABLE_PREFIXES,
-        relationTables: SURREAL_RELATION_TABLES,
-        agentWritableRelationTable: SURREAL_AGENT_LINK_TABLE,
+        configured: Boolean(FALKOR_TOKEN || FALKOR_PASS),
+        endpointConfigured: Boolean(FALKOR_BROWSER_ENDPOINT),
+        graph: FALKOR_GRAPH,
+        nodeLabels: FALKOR_NODE_LABELS,
+        inferredRelationships: FALKOR_INFERRED_RELATIONSHIPS,
+        agentWritableRelationshipType: FALKOR_AGENT_RELATIONSHIP,
         rules: [
-            "Use surreal_graph_query for read-only SELECT, INFO, and EXPLAIN statements.",
-            "SELECT queries must include LIMIT unless they are aggregate count queries.",
-            "Use surreal_graph_link for agent-created relationships; it writes only to lifeos_agent_links.",
-            "Do not mutate Convex-synced entity tables from SurrealDB. Convex remains canonical.",
+            "Use falkor_graph_query for read-only Cypher only.",
+            "MATCH/WITH queries must include LIMIT unless they are aggregate count queries.",
+            "Use falkor_graph_link for agent-created relationships; it writes only AGENT_LINK edges.",
+            "Do not mutate Convex-synced nodes or inferred PPV relationships from FalkorDB. Convex remains canonical.",
             "Every agent link must include a reason and confidence.",
         ],
         examples: {
-            activePpvProjects: 'SELECT id, title, ->ppv_has_pillar->ppv1_pillars.{id, name, ->ppv_pillar_supports_project->lifeos_pmProjects.{id, name, status}} AS pillars FROM ppv1_visions WHERE status = "in_progress" LIMIT 1;',
-            projectInboundLinks: "SELECT <-ppv_pillar_supports_project<-ppv1_pillars.{id, name, purpose} AS supportedByPillars FROM lifeos_pmProjects:`PROJECT_ID` LIMIT 1;",
-            agentLinks: "SELECT id, in, out, kind, reason, confidence, createdBy, createdAt FROM lifeos_agent_links LIMIT 25;",
+            ppvOverview: "MATCH (v:PpvVision)-[:HAS_PILLAR]->(p:PpvPillar)-[:PILLAR_SUPPORTS_PROJECT]->(project:PpvProject) RETURN v.convexId, v.title, p.convexId, p.title, project.convexId, project.title LIMIT 25",
+            projectInboundLinks: "MATCH (pillar:PpvPillar)-[:PILLAR_SUPPORTS_PROJECT]->(project:PpvProject {convexId: 'PROJECT_ID'}) RETURN pillar.convexId, pillar.title, project.title LIMIT 10",
+            agentLinks: "MATCH (a)-[r:AGENT_LINK]->(b) RETURN a.convexId, type(r), r.kind, r.reason, r.confidence, b.convexId LIMIT 25",
         },
     };
 }
-async function surrealGraphQuery(args) {
+async function falkorGraphQuery(args) {
     const query = args.query;
     if (typeof query !== "string") {
         throw new Error("query is required.");
     }
-    assertReadOnlySurrealSql(query);
-    const results = await runSurrealSql(query);
-    return capSurrealResults(results, clampMaxRows(args.maxRows));
+    assertReadOnlyFalkorCypher(query);
+    return capFalkorResult(await runFalkorQuery(query), clampMaxRows(args.maxRows));
 }
-async function surrealGraphLink(args) {
-    const fromTable = assertLifeOsNodeTable(args.fromTable, "fromTable");
+async function falkorGraphLink(args) {
+    const fromLabel = assertFalkorLabel(args.fromLabel, "fromLabel");
     const fromId = assertRecordId(args.fromId, "fromId");
-    const toTable = assertLifeOsNodeTable(args.toTable, "toTable");
+    const toLabel = assertFalkorLabel(args.toLabel, "toLabel");
     const toId = assertRecordId(args.toId, "toId");
     const kind = assertRelationKind(args.kind);
     const reason = assertRecordId(args.reason, "reason");
@@ -6980,8 +6895,9 @@ async function surrealGraphLink(args) {
         ? args.metadata
         : {};
     const now = new Date().toISOString();
-    const linkId = agentLinkId({ fromTable, fromId, toTable, toId, kind });
-    const content = {
+    const linkId = falkorLinkId({ fromLabel, fromId, toLabel, toId, kind });
+    const props = cypherProps({
+        linkId,
         kind,
         reason,
         confidence,
@@ -6989,41 +6905,35 @@ async function surrealGraphLink(args) {
         sourceSystem: "agent",
         sourceUserId: USER_ID,
         userId: USER_ID,
-        sourceTable: fromTable,
-        targetTable: toTable,
-        metadata,
+        metadataJson: JSON.stringify(metadata),
         createdAt: now,
         updatedAt: now,
-    };
-    const sql = [
-        `DEFINE TABLE IF NOT EXISTS ${SURREAL_AGENT_LINK_TABLE} TYPE RELATION SCHEMALESS;`,
-        `DEFINE INDEX IF NOT EXISTS ${SURREAL_AGENT_LINK_TABLE}_kind ON TABLE ${SURREAL_AGENT_LINK_TABLE} COLUMNS kind;`,
-        `DEFINE INDEX IF NOT EXISTS ${SURREAL_AGENT_LINK_TABLE}_createdBy ON TABLE ${SURREAL_AGENT_LINK_TABLE} COLUMNS createdBy;`,
-        `DELETE ${SURREAL_AGENT_LINK_TABLE}:\`${escapeSurrealRecordId(linkId)}\`;`,
-        `RELATE ${surrealThing(fromTable, fromId)}->${SURREAL_AGENT_LINK_TABLE}:\`${escapeSurrealRecordId(linkId)}\`->${surrealThing(toTable, toId)} CONTENT ${JSON.stringify(content)};`,
-    ].join("\n");
-    const results = await runSurrealSql(sql);
+    });
+    await runFalkorQuery(`MATCH (a:${fromLabel} {convexId: ${cypherString(fromId)}})-[r:${FALKOR_AGENT_RELATIONSHIP} {linkId: ${cypherString(linkId)}}]->(b:${toLabel} {convexId: ${cypherString(toId)}}) DELETE r`);
+    const result = await runFalkorQuery(`MATCH (a:${fromLabel} {convexId: ${cypherString(fromId)}}), (b:${toLabel} {convexId: ${cypherString(toId)}}) CREATE (a)-[r:${FALKOR_AGENT_RELATIONSHIP} ${props}]->(b) RETURN r.linkId AS linkId, r.kind AS kind, r.reason AS reason, r.confidence AS confidence`);
     return {
         linked: true,
-        relationId: `${SURREAL_AGENT_LINK_TABLE}:${linkId}`,
-        from: `${fromTable}:${fromId}`,
-        to: `${toTable}:${toId}`,
+        relationType: FALKOR_AGENT_RELATIONSHIP,
+        relationId: linkId,
+        from: `${fromLabel}:${fromId}`,
+        to: `${toLabel}:${toId}`,
         kind,
-        results,
+        result,
     };
 }
-async function surrealGraphUnlink(args) {
-    const fromTable = assertLifeOsNodeTable(args.fromTable, "fromTable");
+async function falkorGraphUnlink(args) {
+    const fromLabel = assertFalkorLabel(args.fromLabel, "fromLabel");
     const fromId = assertRecordId(args.fromId, "fromId");
-    const toTable = assertLifeOsNodeTable(args.toTable, "toTable");
+    const toLabel = assertFalkorLabel(args.toLabel, "toLabel");
     const toId = assertRecordId(args.toId, "toId");
     const kind = assertRelationKind(args.kind);
-    const linkId = agentLinkId({ fromTable, fromId, toTable, toId, kind });
-    const results = await runSurrealSql(`DELETE ${SURREAL_AGENT_LINK_TABLE}:\`${escapeSurrealRecordId(linkId)}\`;`);
+    const linkId = falkorLinkId({ fromLabel, fromId, toLabel, toId, kind });
+    const result = await runFalkorQuery(`MATCH (a:${fromLabel} {convexId: ${cypherString(fromId)}})-[r:${FALKOR_AGENT_RELATIONSHIP} {linkId: ${cypherString(linkId)}}]->(b:${toLabel} {convexId: ${cypherString(toId)}}) DELETE r`);
     return {
         unlinked: true,
-        relationId: `${SURREAL_AGENT_LINK_TABLE}:${linkId}`,
-        results,
+        relationType: FALKOR_AGENT_RELATIONSHIP,
+        relationId: linkId,
+        result,
     };
 }
 const STATIC_RESOURCES = [
@@ -7408,18 +7318,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
-        if (name === "surreal_graph_schema") {
+        if (name === "falkor_graph_schema") {
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify(surrealGraphSchema(), null, 2),
+                        text: JSON.stringify(falkorGraphSchema(), null, 2),
                     },
                 ],
             };
         }
-        if (name === "surreal_graph_query") {
-            const result = await surrealGraphQuery(args || {});
+        if (name === "falkor_graph_query") {
+            const result = await falkorGraphQuery(args || {});
             return {
                 content: [
                     {
@@ -7429,8 +7339,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
-        if (name === "surreal_graph_link") {
-            const result = await surrealGraphLink(args || {});
+        if (name === "falkor_graph_link") {
+            const result = await falkorGraphLink(args || {});
             return {
                 content: [
                     {
@@ -7440,8 +7350,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
-        if (name === "surreal_graph_unlink") {
-            const result = await surrealGraphUnlink(args || {});
+        if (name === "falkor_graph_unlink") {
+            const result = await falkorGraphUnlink(args || {});
             return {
                 content: [
                     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starascendin/lifeos-mcp",
-  "version": "0.7.67",
+  "version": "0.7.69",
   "description": "MCP server for LifeOS Project Management - manage projects, tasks, notes, and contacts via AI assistants",
   "type": "module",
   "main": "dist/index.js",