@rubytech/create-realagent 1.0.710 → 1.0.713

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/connections.md

@@ -31,7 +31,7 @@ The real column header is **line 4**. Either skip the first three lines before p
 | Position | `[:WORKS_FOR].title` |
 | Connected On | `[:CONNECTED_ON_LINKEDIN].connectedOn` (ISO 8601) |
 
-LinkedIn only emits email for connections who opted in, so most rows have a blank email. Write `email` only when non-empty — avoids colliding with `person_email_unique` on empty strings.
+LinkedIn only emits email for connections who opted in, so most rows have a blank email. The MCP tool writes `email` only when non-empty — avoids colliding with `person_email_unique` on empty strings.
 
 ## Natural keys
 
@@ -42,81 +42,52 @@ LinkedIn only emits email for connections who opted in, so most rows have a blan
 
 ## Anchor
 
-```cypher
-MATCH (owner:AdminUser {userId: $ownerUserId})
-```
+Resolved at skill start via the owner-confirmation flow. The owner is either an `:AdminUser` (the operator's own archive — the common case) or a confirmed `:Person` (an external archive ingested for reference). Both flow through the same write tool — `memory-archive-write` matches by `elementId(owner)` and accepts either label set.
 
-Resolved at skill start via the owner-confirmation flow. The owner could instead be a `:Person` if the operator confirmed an external-Person anchor; in that case swap the MATCH to `MATCH (owner:Person) WHERE elementId(owner) = $ownerPersonId` and keep the rest identical — the edges are the same regardless.
+## Selective-ingest threshold
 
-## Cypher
+**100 rows.** When the parsed `rows[]` count exceeds this, the skill pauses before the write call and asks the operator to filter by Company, Position, or Connected On range. See [SKILL.md § Selective-ingest threshold](../SKILL.md#selective-ingest-threshold-bulk-archives) for the doctrine. The MCP tool accepts whatever rows are passed; this gate is conversational.
 
-```cypher
-// Parameters:
-//   $ownerUserId — AdminUser.userId of the confirmed archive owner
-//   $accountId   — Organization accountId scope for this import
-//   $sessionId   — UUID generated once per skill run
-//   $rows        — array of objects:
-//     {
-//       givenName:   "Dee",
-//       familyName:  "Odus",
-//       linkedinUrl: "https://www.linkedin.com/in/deeodus",
-//       email:       null | "someone@example.com",
-//       company:     null | "Female Founders Fund",
-//       title:       null | "Partner",
-//       connectedOn: "2026-04-23"   // ISO 8601, parsed from "23 Apr 2026"
-//     }
-
-MATCH (owner:AdminUser {userId: $ownerUserId})
-UNWIND $rows AS row
-
-// 1. Upsert the connection Person. linkedinUrl is the natural key.
-MERGE (p:Person {linkedinUrl: row.linkedinUrl})
-  ON CREATE SET
-    p.accountId       = $accountId,
-    p.source          = 'linkedin',
-    p.createdByAgent  = 'linkedin-import',
-    p.createdBySource = 'linkedin-import',
-    p.createdBySession= $sessionId,
-    p.createdAt       = datetime()
-SET
-    p.givenName = row.givenName,
-    p.familyName= row.familyName,
-    p.name      = trim(coalesce(row.givenName,'') + ' ' + coalesce(row.familyName,''))
-
-// 1a. Email only when non-empty (avoids person_email_unique collisions on empty strings)
-FOREACH (_ IN CASE WHEN row.email IS NOT NULL AND row.email <> '' THEN [1] ELSE [] END |
-  SET p.email = row.email
-)
-
-// 2. The CONNECTED_ON_LINKEDIN edge is what this CSV means.
-MERGE (owner)-[c:CONNECTED_ON_LINKEDIN]->(p)
-  ON CREATE SET
-    c.connectedOn = date(row.connectedOn),
-    c.source      = 'linkedin',
-    c.createdAt   = datetime()
-
-// 3. If the row names a current employer, create the Organization and WORKS_FOR edge.
-//    If no company is named, this block no-ops — we do not synthesise one.
-WITH p, row
-WHERE row.company IS NOT NULL AND row.company <> ''
-MERGE (o:Organization {accountId: $accountId, name: trim(row.company)})
-  ON CREATE SET
-    o.source          = 'linkedin',
-    o.createdByAgent  = 'linkedin-import',
-    o.createdBySource = 'linkedin-import',
-    o.createdBySession= $sessionId,
-    o.createdAt       = datetime()
-
-MERGE (p)-[w:WORKS_FOR]->(o)
-  ON CREATE SET
-    w.title     = row.title,
-    w.source    = 'linkedin',
-    w.current   = true,
-    w.createdAt = datetime()
-  ON MATCH SET
-    w.title     = coalesce(row.title, w.title)
+## Write surface
+
+This reference invokes a single MCP tool: `mcp__memory__memory-archive-write` with `archiveType: "linkedin-connections"`. The Cypher body — Person upsert by `linkedinUrl`, `CONNECTED_ON_LINKEDIN` edge from owner, optional `:Organization` + `WORKS_FOR` when company is non-empty — lives server-side in [`platform/plugins/memory/mcp/src/tools/memory-archive-write.ts`](../../../../memory/mcp/src/tools/memory-archive-write.ts). The agent does not author or pipe Cypher; it parses CSV rows into the tool's row schema and dispatches one (or more, for filtered re-imports) tool call.
+
+### Tool input shape
+
+```json
+{
+  "archiveType": "linkedin-connections",
+  "ownerNodeId": "<elementId of :AdminUser or :Person — from owner-confirmation flow>",
+  "rows": [
+    {
+      "givenName": "Dee",
+      "familyName": "Odus",
+      "linkedinUrl": "https://www.linkedin.com/in/deeodus",
+      "email": null,
+      "company": "Female Founders Fund",
+      "title": "Partner",
+      "connectedOn": "2026-04-23"
+    }
+  ],
+  "sessionId": "<UUID generated once per skill run>"
+}
 ```
 
+The parser converts:
+- Blank cells → `null` (especially `email`, `company`, `title`).
+- `Connected On` from `"23 Apr 2026"` → ISO 8601 `"2026-04-23"`. The tool rejects rows with non-ISO dates loudly — never let the agent paper over a parser bug.
+
+### What the server does (informational, not the agent's responsibility)
+
+Per 500-row batch the handler runs one transaction with two phases:
+
+1. Upsert each row's `:Person` (natural key `linkedinUrl`), stamp provenance + email when present, then upsert the owner→Person `CONNECTED_ON_LINKEDIN` edge with `connectedOn` on the edge.
+2. For rows whose `company` is non-empty, upsert the `:Organization` (natural key `accountId + name`), then upsert the Person→Organization `WORKS_FOR` edge with `title` on the edge.
+
+Provenance stamped on every node: `source='linkedin'`, `createdByAgent='linkedin-import'`, `createdBySource='linkedin-import'`, `createdBySession=<sessionId>`, `createdAt=<now>`.
+
+Counters come from the Neo4j driver's per-statement summary (`nodesCreated`, `relationshipsCreated`). The tool returns `{processedRows, createdPersons, mergedPersons, createdOrganizations, createdEdges, errors[]}`.
+
 ## Edge semantics — why these and no others
 
 - **`(owner)-[:CONNECTED_ON_LINKEDIN]->(:Person)`** — each row of Connections.csv is a declaration that the archive owner and this person are LinkedIn connections. That's the edge.
@@ -128,14 +99,16 @@ Rows missing a position but present with a company produce a `WORKS_FOR` edge wi
 
 ## Date parsing
 
-`Connected On` arrives as `"23 Apr 2026"`. Convert to ISO 8601 (`2026-04-23`) in the parser before passing to Cypher — `date("2026-04-23")` is Neo4j-native.
+`Connected On` arrives as `"23 Apr 2026"`. Convert to ISO 8601 (`2026-04-23`) in the parser before passing to the tool. The server converts to Neo4j `date()` internally — the agent never invokes Cypher functions.
 
 ## Expected shape
 
-- ~3,000–10,000 rows typical for a long-running account.
-- 500 rows per transaction. Single UNWIND handles this; `apoc.periodic.iterate` not required.
+- ~3,000–10,000 rows typical for a long-running account. The selective-ingest gate (above) keeps a typical write at well under 1,000 rows.
+- 500 rows per transaction. The MCP tool handles batching internally; the agent passes the full filtered `rows[]` in one call.
 
-## Post-import verification
+## Post-import verification (operator-side, not agent-side)
+
+After ingest, the operator can verify counts via the `database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 // Owner → connections count
@@ -145,18 +118,16 @@ RETURN count(p) AS connections;
 // LinkedIn-origin organizations count
 MATCH (o:Organization {accountId: $accountId, source: 'linkedin'})
 RETURN count(o) AS organizations;
-
-// Spot-check: who works at Female Founders Fund?
-MATCH (o:Organization {accountId: $accountId, name: 'Female Founders Fund'})
-      <-[:WORKS_FOR]-(p:Person)
-RETURN p.name, p.linkedinUrl;
 ```
 
+These are **read queries**, not writes. Cypher writes from the agent are forbidden.
+
 ## Failure modes
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
 | Every row parsed as "Notes:,NaN,…" | Header preamble not skipped | Skip first 3 lines before the CSV parser |
-| Constraint violation on `person_email_unique` | Empty email cells treated as `""` instead of `null` | Ensure the parser converts blanks to `null` |
-| `MATCH (owner …)` returns zero rows | `$ownerUserId` invalid — owner-confirmation not run, or operator typed the wrong id | Re-run owner confirmation |
+| Tool error "row connectedOn is not ISO 8601" | Parser left `Connected On` in `"23 Apr 2026"` form | Convert to `YYYY-MM-DD` before passing to the tool |
+| Tool error "ownerNodeId not found" | Owner-confirmation flow not run, or operator typed the wrong id | Re-run owner confirmation; pass the resulting `elementId` as `ownerNodeId` |
 | `WORKS_FOR` count « connection count | Many rows have blank company | Expected — LinkedIn doesn't force connections to list a current employer |
+| Tool not present in `init` frame | `database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/profile.md

@@ -1,8 +1,8 @@
 # Reference: Profile.csv
 
-Enriches the confirmed archive owner's `:UserProfile` with the LinkedIn profile fields. No new nodes, no new edges — `:AdminUser` and `:UserProfile` already exist for any Maxy operator and are linked by `[:HAS_PROFILE]` at session start.
+Enriches the confirmed archive owner's `:UserProfile` with the LinkedIn profile fields. No new nodes, no new edges — `:AdminUser` and `:UserProfile` already exist for any Maxy operator and are linked by `[:HAS_PROFILE]` at session start (neo4j-store handles that on session boot, not this skill).
 
-Runs before every other reference because later files display LinkedIn profile fields (headline, summary) on the owner node they MATCH.
+Runs before every other reference because later files display LinkedIn profile fields (headline, summary) on the owner node they search.
 
 ## Source
 
@@ -30,66 +30,59 @@ Schema.org camelCase per `platform/plugins/memory/references/schema-base.md`.
 
 ## Anchor
 
+The owner-confirmation flow at the start of the skill resolves the operator's `:UserProfile` elementId — not just the `:AdminUser` userId. That elementId (`$ownerProfileElementId`) is the input to this reference. The `[:HAS_PROFILE]` edge between `:AdminUser` and `:UserProfile` is created by `platform/ui/app/lib/neo4j-store.ts` on every session start; it pre-exists by the time any skill runs.
+
+## Write surface
+
+This reference invokes `mcp__memory__memory-update` once with the parsed row's properties:
+
+```json
+{
+  "nodeId": "<elementId of :UserProfile from owner-confirmation>",
+  "properties": {
+    "givenName": "Joel",
+    "familyName": "Smalley",
+    "additionalName": null,
+    "address": null,
+    "birthDate": null,
+    "headline": "Founder, Rubytech",
+    "description": "Building Maxy …",
+    "industry": "Software",
+    "postalCode": null,
+    "addressLocality": "London, UK",
+    "twitterHandles": ["@joelsmalley"],
+    "websites": ["https://getmaxy.com"],
+    "instantMessengers": [],
+    "linkedinProfileUpdatedAt": "<ISO 8601 timestamp>",
+    "source": "linkedin"
+  }
+}
 ```
-(:AdminUser {userId: $ownerUserId}) -[:HAS_PROFILE]-> (:UserProfile {accountId, userId})
-```
-
-The skill run has already persisted `$ownerUserId` (and its resolved `$accountId`) from the owner-confirmation flow. This reference trusts those parameters.
-
-## Cypher
 
-```cypher
-// Parameters:
-//   $ownerUserId — AdminUser.userId of the confirmed archive owner
-//   $accountId   — the UserProfile accountId resolved alongside $ownerUserId
-//   $sessionId   — UUID generated once per skill run
-//   $row         — parsed object with the columns above
-
-MATCH (au:AdminUser {userId: $ownerUserId})
-MERGE (au)-[:HAS_PROFILE]->(up:UserProfile {accountId: $accountId, userId: $ownerUserId})
-  ON CREATE SET
-    up.createdAt       = datetime(),
-    up.createdByAgent  = 'linkedin-import',
-    up.createdBySource = 'linkedin-import',
-    up.createdBySession= $sessionId
-SET
-    up.givenName          = $row.givenName,
-    up.familyName         = $row.familyName,
-    up.additionalName     = $row.additionalName,
-    up.address            = $row.address,
-    up.birthDate          = $row.birthDate,
-    up.headline           = $row.headline,
-    up.description        = $row.description,
-    up.industry           = $row.industry,
-    up.postalCode         = $row.postalCode,
-    up.addressLocality    = $row.addressLocality,
-    up.twitterHandles     = $row.twitterHandles,
-    up.websites           = $row.websites,
-    up.instantMessengers  = $row.instantMessengers,
-    up.linkedinProfileUpdatedAt = datetime(),
-    up.source             = coalesce(up.source, 'linkedin')
-
-RETURN elementId(up) AS ownerProfileElementId
-```
+The `memory-update` tool ignores restricted keys (`embedding`, `accountId`, `createdAt`) and recomputes the embedding from the new property set. No raw Cypher, no `MERGE`, no Bash.
 
-The `MERGE (au)-[:HAS_PROFILE]->(up)` is idempotent: for any operator whose session has already run, `(au)-[:HAS_PROFILE]->(up)` already exists — this statement simply matches it and SETs properties. If the operator has never opened a Maxy session for this account (rare; the UserProfile normally exists before any skill runs), it is created here.
+The parser converts:
+- Blank cells → `null`.
+- `Twitter Handles`, `Websites`, `Instant Messengers` from comma-delimited strings → arrays.
+- `Birth Date` to ISO 8601 if present.
 
 ## Expected outcome
 
-- Zero new nodes (typical case).
-- Zero new edges (typical case).
+- Zero new nodes.
+- Zero new edges.
 - One existing `:UserProfile` enriched with 10–13 new properties.
-- `ownerProfileElementId` returned for downstream references that want to cache the anchor.
 
 ## Failure modes
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| Zero rows returned from `MATCH (au:AdminUser {userId: $ownerUserId})` | `$ownerUserId` doesn't resolve — operator typo in confirmation, or AdminUser missing | Re-run the owner-confirmation flow; verify `platform/config/users.json` contains the expected userId |
+| Tool error "node not found" | `$ownerProfileElementId` invalid — owner-confirmation flow did not return a UserProfile | Re-run the owner-confirmation flow; verify `:AdminUser`-`HAS_PROFILE`->`:UserProfile` exists for the confirmed userId |
 | `up.websites` written as a single string not an array | Parser didn't split on `,` | Fix parser — LinkedIn comma-delimits these fields |
-| Constraint violation on `user_profile_account_user_unique` | Shouldn't happen — MERGE uses the composite key | Indicates a pre-existing duplicate; investigate with `MATCH (up:UserProfile {accountId: $accountId, userId: $ownerUserId}) RETURN count(up)` |
+| Restricted property silently ignored | `memory-update` rejects `embedding` / `accountId` / `createdAt` overrides | Expected — those fields are managed by the server |
+
+## Post-import verification (operator-side, read-only)
 
-## Post-import verification
+A direct read query through `mcp__memory__memory-search` (`labels: ["UserProfile"]`) or `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 MATCH (au:AdminUser {userId: $ownerUserId})-[:HAS_PROFILE]->(up:UserProfile)
@@ -99,4 +92,4 @@ RETURN
   up.websites, up.linkedinProfileUpdatedAt
 ```
 
-Exactly one row. If zero, either the AdminUser doesn't exist or the HAS_PROFILE edge wasn't MERGEd — investigate before running any subsequent reference.
+Exactly one row. If zero, the owner-confirmation flow returned the wrong elementId — investigate before running any subsequent reference.

package/payload/platform/plugins/memory/PLUGIN.md

@@ -19,6 +19,7 @@ tools:
   - memory-read-attachment
   - memory-edit-attachment
   - memory-rename-attachment
+  - memory-archive-write
   - conversation-list
   - conversation-search
   - profile-read

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

@@ -12,6 +12,7 @@ import { buildLiveSchemaSource, defaultSchemaCypherPath, } from "./lib/live-sche
 import { memoryReindex } from "./tools/memory-reindex.js";
 import { memoryIngestExtract } from "./tools/memory-ingest-extract.js";
 import { memoryIngest } from "./tools/memory-ingest.js";
+import { memoryArchiveWrite } from "./tools/memory-archive-write.js";
 import { memoryIngestWeb } from "./tools/memory-ingest-web.js";
 import { memoryClassify } from "./tools/memory-classify.js";
 import { memoryUpdate } from "./tools/memory-update.js";
@@ -769,6 +770,53 @@ if (!readOnly) {
             };
         }
     });
+    server.tool("memory-archive-write", "Bulk-archive write surface (Task 744). Writes a flat dataset (typed entities + natural edges) into the graph " +
+        "in 500-row UNWIND batches. The Cypher body is fixed server-side per `archiveType`; the agent supplies parsed " +
+        "rows + the discriminant, never raw Cypher. Use ONLY for first-class entity exports (LinkedIn Connections, " +
+        "future CRM-type seed exports). Use memory-ingest for narrative documents (KnowledgeDocument + Section + NEXT) " +
+        "and memory-write for single-node operator-driven writes. Currently supported archiveType values: " +
+        "`linkedin-connections`.", {
+        archiveType: z
+            .enum(["linkedin-connections"])
+            .describe("Discriminant naming the per-source schema and Cypher body the server runs. Add a new value here only when the corresponding handler is added in memory-archive-write.ts."),
+        ownerNodeId: z
+            .string()
+            .min(1)
+            .describe("elementId of the archive owner — :AdminUser for an operator's own archive, or :Person for an external-archive owner. Confirmed during the skill's owner-confirmation flow before this tool is invoked."),
+        rows: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe("Parsed rows. The skill's selective-ingest gate runs BEFORE this tool — large blanket archives get filtered (Company / Position / Connected On range for linkedin-connections) before the write call."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Skill-run UUID for provenance stamping. Falls back to SESSION_ID env var when absent."),
+    }, async ({ archiveType, ownerNodeId, rows, sessionId: sessionIdOverride }) => {
+        try {
+            const result = await memoryArchiveWrite({
+                archiveType,
+                ownerNodeId,
+                accountId,
+                rows: rows,
+                sessionId: resolveSessionId(sessionIdOverride),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-archive-write failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
     server.tool("memory-ingest-web", "Adapter for web-content ingestion (Task 737). Accepts a URL and its pre-fetched readable content " +
         "(the agent calls WebFetch first, then passes the text here), writes content to a temp file, and delegates " +
         "to memory-ingest-extract — caching the text under a freshly-generated attachmentId. The skill then drives " +