Forkable reference agent templates: research, RAG, and monitor over the MCP triad #28

Activity

1. harrymove-ctrl

   added this to the Sui Overflow milestone on Jun 16, 2026
2. harrymove-ctrl

   added

   P2Post-demo: distribution, polish, and reliabilityPost-demo: distribution, polish, and reliability

   featureUser- or agent-facing capabilityUser- or agent-facing capability

   onboardingUser and developer onboarding / first-run experienceUser and developer onboarding / first-run experience

   agent-talusTalus/Nexus agent integration and attribution receiptsTalus/Nexus agent integration and attribution receipts

   on Jun 16, 2026
3. harrymove-ctrl commented on Jun 19, 2026

   

   harrymove-ctrl

   on Jun 19, 2026

   OwnerAuthor

   More actions

   Implementation Plan

   Approach
   Add a new top-level examples/ directory with five forkable artifacts (research-agent, rag-chat, monitor-agent, a combined mcpServers config, and a clearly-labeled nexus-dag scaffold), each driving ContextMEM purely over MCP — the hosted read MCP via mcp-remote/StreamableHTTP, and the local write MCP via stdio (bun .../packages/mcp/src/index.ts). Key design decision: templates are decoupled from monorepo internals (own package.json + .env.example per template, kept OUT of root workspaces so a fork is genuinely standalone), while an in-repo examples/tsconfig.json + bun run typecheck:examples (wired into CI) keeps them green by resolving against the root-hoisted @modelcontextprotocol/sdk + zod. Because there is no published npm @contextmem/mcp yet (it is private:true, exports → ./src/index.ts) and no on-chain receipt.id/parents, the plan defaults to the install paths that work today and marks the Nexus receipt fields as scaffold-only.

   Prerequisites & dependencies

   • Hard dep — canonical triad issue (stable tool contract). The local write tools today expose inline, un-exported zod schemas in packages/mcp/src/index.ts; the hosted read tools export TS result types from @contextmem/mcp/hosted (HostedSearchResult, HostedNamespaceSummary, etc.). Templates should import the canonical shared schemas once that issue lands; until then they pin a small local contract.ts mirroring the real I/O (documented as “replace with the published schema”).
   • Soft dep — publish issue (@contextmem/mcp on npm). Until it ships there is no npx @contextmem/mcp: WRITE toolset is clone-based (bun <repo>/packages/mcp/src/index.ts), READ toolset is npx -y mcp-remote <hosted-url>. State both in every README.
   • Soft dep — on-chain attribution-receipt issue. Tools currently return WalrusStorageReceipt (packages/core/src/types.ts:654) = { provider:"tatum", jobId, blobId?, artifactDigest?, certified, downloadUrls?, ... } with no id and no parents. The nexus-dag example is a scaffold that maps those to the future Move receipt struct (roadmap §2: op, namespace, producer, source_digest, artifact_digest, walrus_blob_id, parents: vector<ID>).
   • Credentials/bindings the templates need (document in each .env.example):
     • Local write toolset: MEMWAL_ACCOUNT_ID + MEMWAL_PRIVATE_KEY (64-char Ed25519 hex) — required by MemWalMcpClient (packages/memwal/src/index.ts:85-89); CONTEXTMEM_RUNS_DIR; and TATUM_API_KEY (mainnet) + TATUM_STORAGE_URL only if calling upload_proof_to_walrus (README.md:123).
     • Hosted read toolset: CONTEXTMEM_MCP_URL (default https://contextmem-backend.petlofi.workers.dev/mcp?namespace=<ns>, worker.ts:4601-4605), CONTEXTMEM_NAMESPACE, and CONTEXTMEM_READ_TOKEN (ctxm_…) sent as Authorization: Bearer <token> — required for private namespaces (worker.ts:779; auth check store.authorizeNamespace).
     • Optional for the chat/answer turn: OPENAI_API_KEY / OpenRouter base+model (templates degrade to printing grounded sources if unset).
   • No new Cloudflare bindings or Sui wallet are required for these templates.

   Step-by-step

   1. Scaffold examples/ + shared contract + tooling.

      • Create examples/README.md (index table of the 5 templates, the “which install path works today” note, and the env-matrix above).
      • Create examples/tsconfig.json extending tsconfig.base.json with noEmit and include: ["*/src/**/*.ts", "_shared/**/*.ts"].
      • Create examples/_shared/contract.ts: re-export hosted result types from @contextmem/mcp/hosted and define a minimal triad I/O + a placeholder ReceiptEnvelope type ({ id?: string; parents?: string[]; blobId?: string; artifactDigest?: string; jobId: string; certified: boolean }) with a comment that id/parents await the Move receipt module. Create examples/_shared/mcpClient.ts helpers: connectStdioWrite() (StdioClientTransport spawning bun <repo>/packages/mcp/src/index.ts) and connectHostedRead({url, token}) (StreamableHTTPClientTransport with requestInit.headers.Authorization). Imports: @modelcontextprotocol/sdk/client/index.js, .../client/stdio.js, .../client/streamableHttp.js.
      • Root package.json: add "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit" and append it to the check script. Do not add examples/* to workspaces (keeps forks standalone).

   2. (Recommended enabling change) Expose a web build tool in the local MCP. Today buildAgentReadableSite is imported but never registered as a tool (packages/mcp/src/index.ts:8); the only run-dir-producing tool is extract_walrus_context (index.ts:114-131, Walrus-only). Add a build_web_context tool (wraps buildAgentReadableSite, writes a run under runsDir, returns { runDir }) so the research/monitor web flow is pure-MCP extract → remember. Without it, web templates must shell the contextmem CLI to create a run, or target Walrus sites. (Small, isolated; lives in the executing engineer’s scope, not this plan.)

   3. examples/research-agent/ — local write MCP (stdio). Files: package.json, tsconfig.json, .env.example, README.md, src/index.ts.

      • Flow: read N source URLs from argv/env → for each, extract (build_web_context from step 2, or extract_walrus_context for *.wal.app, index.ts:114) → remember via remember_site_snapshot({ runDir, namespace }) (index.ts:161-186) → recall via recall_site_context({ namespace, query }) (index.ts:234-241) to answer the question; print the answer. Document the LangGraph variant as an optional swap-in (same MCP calls inside graph nodes).
      • Gotcha to surface in README: remember_site_snapshot needs a run dir (context/manifest.json); that is exactly why step 2 matters for web sources.

   4. examples/rag-chat/ — hosted read MCP (StreamableHTTP). Files as above + src/index.ts.

      • Per-turn loop: call get_context_bundle({ query }) (hosted, packages/mcp/src/hosted.ts:220-259) which returns { summary, searchResults[], excerpts[], memory }; searchResults carry sourceLabel/sourceTarget/snippet (hosted.ts:48-57). This is the concrete answer to the issue’s “recall with includeSources” — there is no literal includeSources flag; get_context_bundle/search_context are the source-grounded tools. Build a cited prompt, call the LLM (OpenRouter/OpenAI via fetch) or print grounded sources if no key; cite sources every turn.
      • README must show the private-namespace header (Authorization: Bearer $CONTEXTMEM_READ_TOKEN) and a one-line note that public namespaces need no token (mirrors worker.ts:8024 hint).

   5. examples/monitor-agent/ — local write MCP (stdio), mirrors the live */30 freshness pattern. Files as above + src/index.ts + a .last-run.json (gitignored) for prior-run state.

      • Loop (driven by setInterval; README documents the real */30 cron analog): re-extract target into a new run → diff via diff_site_snapshots({ runId, compareToRunId: priorRunId }) (index.ts:287-294, backed by diffRunSnapshots) → if changed, remember only the delta via upload_proof_to_walrus({ runDir, remember:true, namespace, whatChanged:<diff summary> }) (index.ts:188-224) and print “what changed.” README cites the conceptual reuse of diffRunSnapshots + rememberSnapshotDelta/rememberStorageIndex (packages/memwal/src/index.ts:123,164) that power the production cron, and notes that pure per-chunk delta writes are a library-level path (rememberSnapshotDelta) not yet a standalone MCP tool.

   6. examples/mcpServers.example.json + section in examples/README.md — combined config for Claude/Cursor showing ContextMEM (hosted, via mcp-remote with --header Authorization: Bearer <token>) + a second MCP (@tatumio/blockchain-mcp). Reuse the exact snippet shapes from worker.ts:3244-3293 (claudeDesktop/cursor) and README.md:100-121; make the read-token header explicit and add the “public needs no token” caveat. Provide both a private (header) and public (no header) variant.

   7. examples/nexus-dag/ — clearly-labeled scaffold (not a runnable mainnet DAG). Files: README.md, dag.example.{yaml,ts}, src/receipt-flow.ts.

      • Show ≥2 nodes where node A calls a triad tool (e.g. upload_proof_to_walrus), and node B consumes receipt in its parents. Use the ReceiptEnvelope placeholder from step 1. Inline comments mark LIVE today (receipt.blobId, receipt.jobId, receipt.artifactDigest, receipt.certified from WalrusStorageReceipt, core/types.ts:654) vs AWAITING the Move receipt module (receipt.id = Sui object id, parents: vector<ID> lineage; roadmap §2). README doubles as the “first Nexus call” doc and points to the on-chain attribution-receipt issue.

   8. Per-template READMEs + CI. Each template README: prereqs, env (link .env.example), exact run command (bun run start / bun src/index.ts), and both install paths (clone-based write vs mcp-remote read). Append a CI step to .github/workflows/bun-check.yml (bun run typecheck:examples) — note that bun install --frozen-lockfile already hoists @modelcontextprotocol/sdk/zod, so the examples typecheck without being workspaces. Keep .env.example only (no secrets); add examples/**/.env* (except .env.example) to .gitignore.

   New / changed files

   • examples/README.md (index + env matrix + combined-config section)
   • examples/tsconfig.json
   • examples/_shared/contract.ts, examples/_shared/mcpClient.ts
   • examples/research-agent/{package.json,tsconfig.json,.env.example,README.md,src/index.ts}
   • examples/rag-chat/{package.json,tsconfig.json,.env.example,README.md,src/index.ts}
   • examples/monitor-agent/{package.json,tsconfig.json,.env.example,README.md,src/index.ts}
   • examples/mcpServers.example.json
   • examples/nexus-dag/{README.md,dag.example.yaml,dag.example.ts,src/receipt-flow.ts}
   • package.json (add typecheck:examples, extend check) — changed
   • .github/workflows/bun-check.yml (add typecheck:examples step) — changed
   • .gitignore (ignore examples/**/.env except .env.example) — changed
   • packages/mcp/src/index.ts (optional step 2: register build_web_context) — changed
   • README.md (link examples/ from DEV Onboarding) — changed

   Test plan

   • Typecheck (CI gate): bun run typecheck:examples passes locally and in bun-check.yml; satisfies AC6’s “documented bun command can typecheck the templates.”
   • research-agent (integration, manual): run against a public Walrus site (extract_walrus_context) or a web URL (via step-2 tool), assert a non-empty recall answer and that remember_site_snapshot returns a MemWal jobId/status. Requires MEMWAL_*.
   • rag-chat (integration, manual): point at a seeded public namespace (no token) and a private namespace (with CONTEXTMEM_READ_TOKEN); assert per-turn output includes ≥1 cited sourceLabel/sourceTarget from get_context_bundle; assert that omitting the token on the private namespace yields the 401/NAMESPACE_TOKEN path (proves the header gotcha is real).
   • monitor-agent (integration, manual): two runs over the same target — first prints “no prior run”, second prints a diff and a remembered delta; with TATUM_API_KEY, assert a certified WalrusStorageReceipt with a real blobId (round-trip proof the delta was stored).
   • combined config (manual): load mcpServers.example.json in Claude Desktop/Cursor; confirm both servers connect and a ContextMEM read tool returns data.
   • nexus-dag (static): typecheck only + a tiny assert in receipt-flow.ts that a mock receipt’s LIVE fields are populated and id/parents are explicitly marked TODO; no on-chain tx expected this milestone.

   Risks & gotchas

   • Silent 401 on private namespaces — the headline trap; every template config must show Authorization: Bearer <read-token> (worker.ts:779). Test the negative case.
   • No npm package yet — @contextmem/mcp is private:true; do not write npx @contextmem/mcp examples until the publish issue lands. Use clone-based write + mcp-remote read.
   • receipt.id/parents don’t exist — only on WalrusStorageReceipt are blobId/jobId/artifactDigest; the nexus-dag must not pretend otherwise (AC5: “mark clearly which parts are live vs awaiting the Move receipt module”).
   • runDir coupling — remember_site_snapshot/upload_proof_to_walrus need a run dir; web extract has no run-producing MCP tool today (only Walrus). Step 2 fixes this cleanly; otherwise document the CLI fallback.
   • Network split — upload_proof_to_walrus requires a mainnet TATUM_API_KEY (README.md:123); recall/remember go through the MemWal relayer. Keep this explicit so users don’t mix testnet creds.
   • Forkability vs in-repo typecheck — templates import @contextmem/mcp/hosted types via the path alias for in-repo TS; a raw fork won’t resolve that. README must tell forkers to copy _shared/contract.ts or install the published package once available.
   • mcp-remote / StreamableHTTP transport — the Worker uses enableJsonResponse:true + corsOptions.origin:"*" (worker.ts:789-792); ensure the client sets Accept: application/json, text/event-stream (the Worker’s acceptsEventStream, worker.ts:812-815) or it serves the HTML landing page instead of MCP.
   • MemWal relayer flakiness — embedding calls can transiently fail (rememberWithRetry, memwal/index.ts:254); templates should tolerate/retry rather than hard-fail.

   Acceptance-criteria mapping

   • AC1 examples/research-agent/ extract→remember→recall, runnable w/ env → Step 3 (+ enabling Step 2).
   • AC2 examples/rag-chat/ recall-grounded chat citing sources via includeSources → Step 4 (get_context_bundle/search_context).
   • AC3 examples/monitor-agent/ re-extract → diff → remember delta, prints “what changed” → Step 5 (diff_site_snapshots + upload_proof_to_walrus whatChanged).
   • AC4 combined mcpServers JSON for Claude/Cursor incl. read-token header → Step 6.
   • AC5 examples/nexus-dag/ scaffold showing receipt.id→parents, live vs awaiting → Step 7.
   • AC6 per-template README + examples/README.md index + CI/bun typecheck → Steps 1, 3-8.

   Effort
   M — ~4 person-days (≈0.5d scaffold/tooling+CI, 0.5d optional build_web_context tool, ~0.75d each for research/rag/monitor incl. README + manual run, 0.5d combined config, 0.5d nexus-dag scaffold + docs). Mostly thin MCP-client glue and docs, no new infra.

   ---

   Implementation plan generated for execution (planning phase). Part of the roadmap (#4).