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

[harrymove-ctrl]

Context

There are no examples/ and no Nexus/Talus 'first agent call' onboarding (roadmap §5 gaps). Agent builders have to reverse-engineer how to drive contextmem_extract/recall/remember from the MCP server in packages/mcp. The roadmap calls for 2-3 runnable templates plus a sample Nexus DAG that calls a tool and emits an on-chain receipt.

Goal / user story

As an agent builder, I want forkable starter templates that already wire the ContextMEM triad over MCP for the three obvious patterns — research, RAG chat, and change-monitoring — so I can clone one, point it at my namespace, and have a working Sui-native agent in minutes.

Acceptance criteria

• examples/research-agent/ — a minimal TS/LangGraph (or plain MCP-client) agent that runs extract over N sources, remembers them to a namespace, then recalls to answer a question; runnable with documented env.
• examples/rag-chat/ — a recall-grounded chat loop that calls recall (with includeSources) against the hosted MCP namespace and cites sources per turn.
• examples/monitor-agent/ — a scheduled agent that re-extracts a target, diffs vs the prior run, and remembers only the delta (mirroring the live */30 freshness pattern), printing 'what changed'.
• A combined mcpServers JSON example shows ContextMEM (and optionally a second MCP) configured together for Claude/Cursor, including the read-token header for private namespaces.
• examples/nexus-dag/ — a sample Talus/Nexus DAG (or a clearly-labeled scaffold) that calls one triad tool as a node and shows where the attribution receipt id flows into parents of the next node.
• Each template has its own README (prereqs, env, run command) and an examples/README.md index; CI or a documented bun command can at least typecheck the templates.

Implementation notes

• Add a top-level examples/ dir; templates consume the published @contextmem/mcp (or the hosted URL via mcp-remote) — keep them decoupled from monorepo internals so they're genuinely forkable.
• Reuse the canonical triad I/O schemas (from the triad issue) as the typed contract; the monitor template should reuse diffRunSnapshots semantics and the delta-write path (rememberSnapshotDelta) conceptually.
• The nexus-dag example should reference the receipt envelope returned by the tools (receipt.id, parents) so it doubles as the 'first Nexus call' doc; mark clearly which parts are live vs awaiting the Move receipt module.
• Gotcha: private namespaces need the Authorization: Bearer <read-token> header — make this explicit in every template's config so users don't hit silent 401s.
• Keep secrets out of committed examples; use .env.example per template.

Sui Overflow angle

These templates are the agent-ecosystem on-ramp for Sui Overflow: research/RAG/monitor are the canonical agent shapes, and shipping them pre-wired to a Walrus-backed, receipt-emitting memory layer lets other hackathon teams build Sui-native agents on top of ContextMEM. The Nexus DAG example is the concrete 'compose ContextMEM into a Talus pipeline' artifact judges can run.

Dependencies

Depends on the canonical triad issue (stable tool contract). Soft-depends on the publish issue (@contextmem/mcp for clean installs) and the on-chain attribution-receipt issue (for the Nexus DAG receipt flow).

Part of the ContextMEM roadmap (#4) • Sui Overflow build.

[harrymove-ctrl]

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).