@rubytech/create-maxy-code 0.1.132 → 0.1.138

package/payload/platform/plugins/docs/references/internals.md

@@ -11,20 +11,29 @@ Use this reference when assessing capabilities, diagnosing retrieval behaviour,
 Every knowledge query flows through a hybrid search pipeline that combines semantic similarity with keyword matching, applies layered access controls, expands results via graph traversal, and optionally re-ranks via LLM reasoning.
 
 ```
-QUERY
+QUERY  ── (retrievalClass from Task 304 gateway-classifier)
   │
-  ├── EMBED (EMBED_MODEL, default nomic-embed-text) ──► VECTOR SEARCH (per index, cosine)
-  │ │
-  │ ├──► MERGE ──► EXPAND ──► RESULTS
-  │ │
-  └── ESCAPE (Lucene special chars) ──────► BM25 FULL-TEXT ──┘
-                                            (entity_search index — universal coverage)
-
-Merge formula: combined = 0.7 × vector_score + 0.3 × normalised_bm25_score
-Deduplication: by nodeId — when a node appears in both paths, keep the max score from each method independently, then combine.
+  ├── EXPAND (Haiku — 3-5 paraphrases, 1h cache)            [flag: MAXY_GS_EXPANSION]
+  │
+  ├── ROUTE  (per-class label filter + fusion weights)      [flag: MAXY_GS_ROUTE]
+  │
+  ├── For each query ────► EMBED ──► VECTOR SEARCH ──┐
+  │                                                  ├─► FUSE (weighted-sum or RRF) [flag: MAXY_GS_RRF]
+  │                  └────► BM25 FULL-TEXT ──────────┘
+  │                         (entity_search — universal coverage)
+  │
+  ├── BOOST  (compiledTruth +15%, backlinks log 5-25%)      [flag: MAXY_GS_BOOSTS]
+  ├── DEDUP  (4 layers: nodeId, slug, canonicalName, hash)  [flag: MAXY_GS_DEDUP]
+  ├── THRESHOLD + SORT + SLICE
+  └── GRAPH EXPAND ──► RESULTS
+
+Fusion (default / weighted-sum): combined = 0.7 × vector + 0.3 × bm25_norm
+Fusion (RRF):                    score = Σ 1 / (60 + rank_i) across ranked lists
 Fallback: if the full-text index doesn't exist, vector-only results are returned (graceful degradation, no error).
 ```
 
+Each Task 308 enhancement is independently flagged. All flags default OFF — the unflagged pipeline is identical to the baseline weighted-sum + nodeId-only-dedup behaviour. Tasks 305 (typed-edge backlinks) and 306 (compiledTruth property) have landed, so the boost data is populated; flag activation, soak windows, and per-flag measurement live under Task 337.
+
 ### Hybrid Search Detail
 
 **Vector path:** The query is embedded via Ollama (model per `EMBED_MODEL` env var, default `nomic-embed-text`). The resulting vector is compared against Neo4j's HNSW cosine indexes — one per indexed label. Dimensions are configured at install time (default 768). The search runs against all discovered indexes (or a subset if the caller specifies label filters). Scores are in [0, 1] (cosine similarity).
@@ -33,6 +42,23 @@ Fallback: if the full-text index doesn't exist, vector-only results are returned
 
 **Merge:** Results from both paths are collected in a single map keyed by `nodeId`. A node appearing in both paths accumulates the max vector score and max BM25 score independently. The combined score is `0.7 * vectorScore + 0.3 * bm25Score`. Results are sorted descending by combined score, then sliced to the requested limit (default 10).
 
+### Task 308 enhancements (flagged, default off)
+
+| Stage | Module | Flag | What it does |
+|---|---|---|---|
+| Routing | `route.ts` | `MAXY_GS_ROUTE` | Picks per-class label filter + fusion weights from the `retrievalClass` hint produced by Task 304's gateway-classifier. `entity` → vector-heavy + Person/Company/Concept; `temporal` → BM25-heavy over Event; `event` → BM25-only over Event; `general` → balanced; `none` → skip the lookup. |
+| Multi-query expansion | `query-expansion.ts` | `MAXY_GS_EXPANSION` | Haiku generates 3-5 paraphrases per query; each runs through vector + BM25 in parallel, with results unioned before fusion. Per-call 1-hour cache keyed by (accountId, query, retrievalClass). Graceful degrade on Haiku failure — original query only. |
+| RRF fusion | `rrf-fusion.ts` | `MAXY_GS_RRF` | Replaces weighted-sum with Reciprocal Rank Fusion (k=60 by default). Sums `1 / (k + rank)` per node across the ranked lists each pass produces. More robust to score-distribution drift between indexes than weighted-sum. Weighted-sum stays as the fallback. |
+| compiledTruth boost | `boosts.ts` | `MAXY_GS_BOOSTS` | +15% to the combined score of any hit whose node carries a non-null `compiledTruth` property (populated by Task 306 on Person/Company/Concept). The property is in the `entity_search` index so BM25 hits against summary text are also matched. |
+| Backlink boost | `boosts.ts` | `MAXY_GS_BOOSTS` | `bump = clamp(0.05 + 0.05 × log10(backlinkCount), 0.05, 0.25)`. 1 backlink → +5%; 10 → +10%; 100 → +15%; 1000+ → +20%; capped at +25%. Reads `backlinkCount` populated by Task 305's typed-edge hook. |
+| 4-layer dedup | `dedup.ts` | `MAXY_GS_DEDUP` | Strict superset of nodeId-only dedup. Layers: `nodeId`, `slug`, `canonicalName` (case-insensitive, falls back to `name`), `contentHash` (sha256 of `compiledTruth || content`). Highest-score representative wins per collision class. Missing keys skip the layer, no false collision. |
+
+A per-call log line lets the operator see which stages ran with which counts:
+
+```
+[graph-search:hybrid] accountId=<8c> retrievalClass=<c> expansions=<n> vector=<n> bm25=<n> fused=<n> boosted=<n> deduped=<n> final=<n> mode=<hybrid|rrf|bm25> ms=<ms> expand-ms=<ms>
+```
+
 ### What the hybrid approach catches
 
 Vector search excels at semantic meaning — "how do I contact someone" finds nodes about communication even if the word "contact" doesn't appear. BM25 excels at exact terms — invoice numbers, product codes, proper nouns, technical identifiers. The hybrid combination ensures both modes contribute, with semantic similarity weighted higher (0.7) because most user queries are natural language.

package/payload/platform/plugins/docs/references/neo4j.md

@@ -0,0 +1,63 @@
+# Neo4j edge types — operator reference
+
+How Maxy's graph wires itself.
+
+## Typed-edge auto-extraction
+
+At the end of every admin session (`/end`, `/archive`, `end session`, `archive this session`), the admin agent delegates one final pass to the `database-operator` specialist. That pass reads every prose-bearing node your account wrote since the last completed retrospective — messages, meetings, notes, pages, posts, reports, emails, ideas — and asks Claude Haiku to propose typed edges from the text. Only edges that match a closed allowlist of `(sourceLabel, EDGE_TYPE, targetLabel)` shapes are MERGEd into the graph. The graph wires itself; you do not have to ask for it.
+
+If a session closes without one of the four typed end-intent tokens (Sidebar Archive, tab-close, power loss), the pass for that session is deferred — its prose nodes land at the next `/end`. Nothing is lost, just delayed by one session.
+
+## Typed-edge allowlist
+
+<!-- TYPED-EDGE-TABLE:START -->
+
+<!-- Generated by platform/plugins/memory/mcp/scripts/generate-edge-docs.ts from TYPED_EDGE_ALLOWLIST. Do not edit by hand. -->
+
+| Source label | Edge type | Target label |
+|---|---|---|
+| Person | ATTENDED | Event |
+| Person | ATTENDED | Meeting |
+| Person | WORKS_AT | Organization |
+| Person | WORKS_AT | LocalBusiness |
+| Person | INVESTED_IN | Organization |
+| Person | INVESTED_IN | LocalBusiness |
+| Organization | INVESTED_IN | Organization |
+| Organization | INVESTED_IN | LocalBusiness |
+| Person | FOUNDED | Organization |
+| Person | FOUNDED | LocalBusiness |
+| Person | ADVISES | Organization |
+| Person | ADVISES | LocalBusiness |
+| Person | ADVISES | Person |
+| Message | MENTIONS | Person |
+| Message | MENTIONS | Organization |
+| Message | MENTIONS | LocalBusiness |
+| Message | MENTIONS | Event |
+| Page | MENTIONS | Person |
+| Page | MENTIONS | Organization |
+| Page | MENTIONS | LocalBusiness |
+| Page | MENTIONS | Event |
+| Meeting | MENTIONS | Person |
+| Meeting | MENTIONS | Organization |
+| Email | MENTIONS | Person |
+| Email | MENTIONS | Organization |
+| Note | MENTIONS | Person |
+| Note | MENTIONS | Organization |
+| Idea | MENTIONS | Person |
+| Idea | MENTIONS | Organization |
+| Post | MENTIONS | Person |
+| Post | MENTIONS | Organization |
+| Report | MENTIONS | Person |
+| Report | MENTIONS | Organization |
+| Person | AUTHORED | Post |
+| Person | AUTHORED | Report |
+| Person | AUTHORED | Page |
+| Person | AUTHORED | Note |
+| Email | ATTACHED_TO | Meeting |
+| Page | ATTACHED_TO | Project |
+| Note | ATTACHED_TO | Project |
+| Page | REFERENCES | Page |
+| Report | REFERENCES | Report |
+| Report | REFERENCES | Page |
+
+<!-- TYPED-EDGE-TABLE:END -->

package/payload/platform/plugins/docs/references/session-retrospective.md

@@ -1,20 +1,27 @@
 # Session-end retrospective
 
-When you end an admin session by typing `/end`, `/archive`, `end session`, or `archive this session`, the admin agent runs one extra turn before the session closes. It walks the session and writes down three kinds of thing that would otherwise be lost:
+When you end an admin session by typing `/end`, `/archive`, `end session`, or `archive this session`, the admin agent runs one extra turn before the session closes. It walks the session and writes down four kinds of thing that would otherwise be lost:
 
 - corrections and learnings you gave the agent during the session,
 - tonal and working-style preferences worth carrying forward,
-- people, decisions, commitments, or business facts that came up but were not yet saved to the graph.
+- people, decisions, commitments, or business facts that came up but were not yet saved to the graph,
+- typed edges between any new prose-bearing nodes (messages, meetings, notes, pages) and the entities they mention — the auto-extraction pass that "wires the graph" so future questions can hop from a person to the companies they founded to the events they attended.
 
 The next session starts against an up-to-date picture of you and your business — not just the parts that got recorded mid-flow.
 
-The extra turn is one or two messages from the agent, then a short summary of what was written. It runs inside the same session you were already in; nothing happens in the background, no second session is spawned.
+The extra turn is one or two messages from the agent, then a short summary of what was written. It runs inside the same session you were already in; nothing happens in the background, no second session is spawned. The typed-edge pass itself is delegated to the `database-operator` specialist so the writes land where graph writes are supposed to live.
 
 ## When the retrospective is skipped
 
 - Clicking the Archive button in the Sidebar closes the session directly and skips the retrospective. The four typed phrases above are the only signals that trigger it.
 - Closing the browser tab or losing power closes the session without the retrospective. The mid-session recording route (the agent writes facts as they come up) is the primary safety net; the retrospective is the catch-net for what slips through.
 
+Skipped sessions do not lose typed-edge work. The next session's retrospective picks up any prose nodes the previous session wrote, because the pass is scoped by "what changed since the last completed retrospective" — not by which session wrote it. The cost of skipping is one session of delay, not lost extraction.
+
+## Skip-rate visibility
+
+At the start of every admin session, the agent checks how many of your recent sessions closed without firing the retrospective. If any did, it surfaces one line — for example, "the last 10 sessions: 4 ended without a retrospective; their typed edges land at the next `/end`." This is informational, not nagging — it lets you choose to end the next session properly so the deferred extraction lands sooner.
+
 ## What you see if the agent tries to skip it
 
-If the agent replies with a prose summary of "what it learned" without actually performing the retrospective, the session does not close — the Stop gate blocks until the agent calls the deterministic completion tool. You can tell it happened correctly by the final reply naming the counts ("I wrote two learnings, one tonal observation, and three graph updates"); the absence of those counts is the signal that something went wrong.
+If the agent replies with a prose summary of "what it learned" without actually performing the retrospective, the session does not close — the Stop gate blocks until the agent calls the deterministic completion tool. You can tell it happened correctly by the final reply naming the five counts (learnings, tonal observations, graph updates, typed edges accepted, prose nodes scanned); the absence of those counts is the signal that something went wrong.

package/payload/platform/plugins/graph-viewer/mcp/dist/tools/graph-render.js

@@ -24,9 +24,9 @@ import { getSession } from "../lib/neo4j.js";
 import { layoutGraph } from "../render/layout.js";
 import { drawGraph } from "../render/draw.js";
 function getAccountsDir() {
-    const root = process.env.MAXY_PLATFORM_ROOT;
+    const root = process.env.PLATFORM_ROOT ?? process.env.MAXY_PLATFORM_ROOT;
     if (!root) {
-        throw new Error("[graph-render] MAXY_PLATFORM_ROOT not set — cannot resolve account output dir.");
+        throw new Error("[graph-render] PLATFORM_ROOT not set (also checked MAXY_PLATFORM_ROOT) — cannot resolve account output dir.");
     }
     return resolve(root, "..", "data/accounts");
 }

package/payload/platform/plugins/graph-viewer/mcp/dist/tools/graph-render.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-render.js","sourceRoot":"","sources":["../../src/tools/graph-render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-render.js","sourceRoot":"","sources":["../../src/tools/graph-render.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -41,6 +41,8 @@ import { conversationMemoryExpunge } from "./tools/conversation-memory-expunge.j
 import { conversationArchiveDeriveInsights, } from "./tools/conversation-archive-derive-insights.js";
 import { conversationArchiveEnrichRejection } from "./tools/conversation-archive-enrich-rejection.js";
 import { fetchImageAsContent } from "./tools/image-fetch.js";
+import { memoryTypedEdgePass } from "./tools/memory-typed-edge-pass.js";
+import { sessionRetrospectiveSkipRate } from "./tools/session-retrospective-skip-rate.js";
 import { getSession, closeDriver } from "./lib/neo4j.js";
 import { embed } from "./lib/embeddings.js";
 import { notTrashed } from "../../../../lib/graph-trash/dist/index.js";
@@ -205,7 +207,11 @@ eagerTool(server, "memory-search", "Search the knowledge graph using semantic ve
         .array(z.string())
         .optional()
         .describe("Narrow the response `properties` to these keys per result. Omit to return all properties (default). Empty array returns no properties (explicit 'none'). Unknown keys are silently skipped; nodes lacking a requested key omit it on that row. Use for known-shape lookups (slug → name) to avoid shipping bios, notes, source URLs on every turn. Ranking is unaffected — hybrid() sees the full text either way. See `references/graph-primitives.md` § Projecting fields."),
-}, async ({ query, labels, limit, expandHops, keywords, keywordMatch, agentSlug: toolAgentSlug, fields }) => {
+    retrievalClass: z
+        .enum(["entity", "temporal", "event", "general", "none"])
+        .optional()
+        .describe("Hint that selects the per-class index mix (route-hint contract). Pass 'entity' for who/what-is-this lookups (vector-heavy, Person|Company|Concept filter), 'temporal' for when-did-this-happen (BM25-heavy over :Event with Timeline), 'event' for pure event listings, 'none' to skip graph lookup entirely (greetings/instructions). Omit or pass 'general' for the balanced default. Routing only takes effect when MAXY_GS_ROUTE is enabled; otherwise the value is recorded in the log line but does not change index selection."),
+}, async ({ query, labels, limit, expandHops, keywords, keywordMatch, agentSlug: toolAgentSlug, fields, retrievalClass }) => {
     if (!accountId)
         return refuseNoAccount("memory-search");
     // Env var takes precedence over tool param (security: public agent server-level enforcement)
@@ -223,6 +229,7 @@ eagerTool(server, "memory-search", "Search the knowledge graph using semantic ve
             agentSlug: effectiveAgentSlug,
             keywordSubscriptions: envKeywordSubscriptions,
             fields,
+            retrievalClass,
         });
         if (results.length === 0) {
             return {
@@ -633,12 +640,20 @@ if (!readOnly) {
             };
         }
     });
-    server.tool("memory-update", "Update properties on an existing node in the knowledge graph. Finds the node by element ID, verifies account ownership, sets the provided properties, and recomputes the embedding.", {
+    server.tool("memory-update", "Update properties on an existing node in the knowledge graph. Finds the node by element ID, verifies account ownership, sets the provided properties, and recomputes the embedding. For :Person / :Organization / :Concept, pass rewriteCompiledTruth=true to recompute the compiled-truth summary from the most recent :TimelineEvent rows; direct writes to compiledTruth / compiledTruthUpdatedAt / compiledTruthSource are refused.", {
         nodeId: z.string().describe("Element ID of the node to update (from memory-search results)"),
         properties: z
             .record(z.string(), z.unknown())
-            .describe("Properties to set or overwrite. Restricted keys (embedding, accountId, createdAt) are ignored."),
-    }, async ({ nodeId, properties }) => {
+            .describe("Properties to set or overwrite. Restricted keys (embedding, accountId, createdAt) are ignored. compiledTruth / compiledTruthUpdatedAt / compiledTruthSource are system-managed and rejected loudly — use rewriteCompiledTruth instead."),
+        rewriteCompiledTruth: z
+            .boolean()
+            .optional()
+            .describe("When true, run the compiled-truth rewriter against the node's most recent :TimelineEvent rows and set the result on compiledTruth. Only valid on :Person / :Organization / :Concept."),
+        forceRewrite: z
+            .boolean()
+            .optional()
+            .describe("Bypass the 7-day cooldown that protects an operator-edited compiledTruth from automatic rewriter passes. Set only when the operator explicitly asks for a refresh."),
+    }, async ({ nodeId, properties, rewriteCompiledTruth, forceRewrite }) => {
         if (!accountId)
             return refuseNoAccount("memory-update");
         try {
@@ -651,12 +666,30 @@ if (!readOnly) {
                     session: resolveSessionId(),
                     tool: "memory-update",
                 },
+                rewriteCompiledTruth,
+                forceRewrite,
             });
+            const rewriterLine = (() => {
+                if (!result.rewriter)
+                    return "";
+                if (result.rewriter.kind === "ok") {
+                    return `\nCompiled-truth rewritten: ${result.rewriter.charsBefore} → ${result.rewriter.charsAfter} chars.`;
+                }
+                if (result.rewriter.kind === "refused") {
+                    return result.rewriter.reason === "operator-edit-cooldown"
+                        ? `\nRewriter refused: operator-edit cooldown (${result.rewriter.daysRemaining} day(s) remaining; pass forceRewrite=true to override).`
+                        : `\nRewriter refused: no :TimelineEvent rows linked to this node.`;
+                }
+                if (result.rewriter.kind === "too-long") {
+                    return `\nRewriter output exceeded ${result.rewriter.attemptedLen} chars after one retry; compiledTruth unchanged.`;
+                }
+                return `\nRewriter LLM call failed (cause=${result.rewriter.cause}); compiledTruth unchanged.`;
+            })();
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Node updated: [${result.labels.join(", ")}] (ID: ${result.nodeId})`,
+                        text: `Node updated: [${result.labels.join(", ")}] (ID: ${result.nodeId})${rewriterLine}`,
                     },
                 ],
             };
@@ -1954,6 +1987,82 @@ server.tool("image-fetch", [
         ],
     };
 });
+// ===================================================================
+// Typed-edge auto-extraction pass (Task 305)
+// ===================================================================
+//
+// Schema-bounded session-end pass that reads prose-bearing nodes the
+// operator's account wrote since `sinceIso` and asks Haiku for typed-edge
+// proposals against `TYPED_EDGE_ALLOWLIST`. Owned by `database-operator`
+// (admin Task-spawns it at the retrospective turn); NOT in
+// `ADMIN_CORE_TOOLS`. Backfill is via the CLI under `scripts/backfill-typed-edges.ts`,
+// bypassing this tool.
+server.tool("memory-typed-edge-pass", "Run the typed-edge auto-extraction pass over prose-bearing nodes this account wrote since sinceIso. Reads Message/Page/Meeting/Email/Idea/Note/Post/Report nodes, batches them, asks Haiku for typed-edge proposals against the closed allowlist (ATTENDED, WORKS_AT, INVESTED_IN, FOUNDED, ADVISES, MENTIONS, AUTHORED, ATTACHED_TO, REFERENCES), validates each proposal inline, and MERGEs accepted edges with createdBy provenance. Returns the counters (nodes, proposed, accepted, rejected, failed, ms) for the caller to hand back to admin's session-retrospective-mark-complete.", {
+    sinceIso: z.string().describe("ISO timestamp lower bound. Prose nodes with updatedAt >= sinceIso are processed."),
+    conversationId: z.string().optional().describe("Conversation id stamped onto the createdBy provenance of MERGEd edges. Defaults to CONVERSATION_ID env if absent."),
+}, async (args) => {
+    if (!accountId)
+        return refuseNoAccount("memory-typed-edge-pass");
+    const dbSession = getSession();
+    try {
+        const result = await memoryTypedEdgePass(args, dbSession, accountId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Typed-edge pass failed: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+            isError: true,
+        };
+    }
+    finally {
+        await dbSession.close();
+    }
+});
+// ===================================================================
+// Session-retrospective skip-rate (Task 305)
+// ===================================================================
+//
+// Visibility tool the admin agent calls at session start. Returns the ratio
+// of recent sessions for this account that ended WITHOUT calling
+// `session-retrospective-mark-complete` — those sessions skipped the
+// typed-edge pass, learnings pass, and SOUL.md pass. Admin surfaces a
+// one-line note to the operator when the rate is non-zero.
+server.tool("session-retrospective-skip-rate", "Return the ratio of recent sessions for this account that closed without firing the session-retrospective. Skipped retrospectives mean the typed-edge pass, learnings pass, and SOUL.md updates are deferred to the next /end. Use at session start to surface the cost to the operator when non-zero.", {
+    windowSize: z.number().int().positive().optional().describe("Number of most-recent sessions to inspect. Defaults to 10, capped at 100."),
+}, async (args) => {
+    if (!accountId)
+        return refuseNoAccount("session-retrospective-skip-rate");
+    const dbSession = getSession();
+    try {
+        const result = await sessionRetrospectiveSkipRate(args, dbSession, accountId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Skip-rate query failed: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+            isError: true,
+        };
+    }
+    finally {
+        await dbSession.close();
+    }
+});
 // Cleanup on exit
 process.on("SIGINT", async () => {
     liveSchemaRuntime.cache.stop();