docs(mcp): integration guide + @commonlyai/mcp publish prep - #309
Closed
samxu01 wants to merge 8 commits into
Closed
docs(mcp): integration guide + @commonlyai/mcp publish prep#309samxu01 wants to merge 8 commits into
samxu01 wants to merge 8 commits into
Conversation
…cycle tool
Pairs with the trailer re-enable in the next commit. The bumped openclaw
extension exposes commonly_log_cycle({content, podId?}) — a dedicated,
append-only writer for AgentMemory.cycles[] per ADR-012 Phase 2.
Team-Commonly/openclaw PR #7 (squash-merged as a67f0df6).
…y_log_cycle Phase 2.J's withCyclesDirective trailer was rolled back in e4b1dd9 / PR #296 because it instructed agents to call: commonly_save_my_memory({sections:{cycles:{append:...}}}) That tool neither accepts the `cycles` section nor the nested `{sections:{...}}` envelope — agents wasted 3+ tool-call turns per heartbeat hunting for the missing surface before falling back to commonly_write_agent_memory, exhausting their turn budget and dropping DM responses (Nova on 2026-05-04). Forward fix shipped in Team-Commonly/openclaw#7 (a67f0df6, submodule bumped in the previous commit): adds a dedicated commonly_log_cycle({content, podId?}) tool that maps directly onto the kernel's {cycles:{append:{content,podId?}}} contract via /memory/sync. This commit: - Rewrites CYCLES_REFLECTION_TRAILER to call commonly_log_cycle directly, no nested envelope, no missing surface. - Restores withCyclesDirective from no-op to template + trailer. - Replaces the rollback comment block with a re-enable note that preserves the failure-mode archaeology for future readers. After Deploy Dev + reprovision-all, dev agents should produce cycles[] writes inside the next heartbeat window — closing the empirical gap from the original Phase 2 observation (0 agent-authored cycle entries across 25 deployed agents in the +10min window).
Closes the read-side of the memory loop without falling into the always-on prefix anti-pattern. Two paired changes: 1. **Memory-changed cue** in `AgentEventService.enqueue` for chat.mention and thread.mention events. When the target agent's `revision` exceeds `lastSeenRevision`, prepend a single-line cue (~25 tokens) to `payload.content`: `[memory: N new system_exchange entries since your last cycle — call commonly_read_agent_memory if relevant.]` The cue surfaces the FACT of a delta — never the content. Agent decides whether to actually pull. Defensive: any lookup failure silently skips the cue (it's a hint, not a correctness primitive). Heartbeat events are intentionally excluded — they have the HEARTBEAT.md trailer (Phase 2.J) for cycle-write prompting; the chat-side cue is the read-side parallel. Per `feedback-not-building-agents.md`: memory as a tool, not a prefix. Reference platforms (Anthropic memory tool, MemGPT, mem0, MCP memory server) all moved away from always-on injection because of context bloat — Commonly inherits the same pattern. 2. **MCP memory tools** in `@commonly/mcp`. Added `commonly_save_my_memory` (per-section patch via /memory/sync) and `commonly_log_cycle` (the ADR-012 Phase 2 append-only cycles writer). These mirror the openclaw extension surface so any MCP-capable runtime — Claude Code, Cursor, Codex (via wrapper) — gets identical memory primitives without per-runtime stitching. Existing `commonly_read_agent_memory` and `commonly_write_agent_memory` were already present. Together: every Commonly runtime now has the same cue + tool contract. Agents see "memory changed" inline, decide whether it's relevant, and pull on demand via a tool whose name + signature is identical across openclaw, MCP, and webhook adapters.
…ge README Tier 1 followup to ADR-012 Phase 4. Two new docs: 1. **docs/MCP_INTEGRATION.md** — operator walkthrough. Covers: - What the 16 tools cover (messaging / tasks / pods / memory groups) - Memory contract (cue + tool, NOT always-on injection) - Token provisioning via `commonly agent init` - Wire-up for Claude Code (`claude mcp add` + .claude.json) - Wire-up for Cursor (~/.cursor/mcp.json) - Codex via wrapper or ADR-005 local CLI pattern - Auth notes, troubleshooting table, cross-refs 2. **commonly-mcp/README.md** — npm-package-facing README. Concise install, quickstart for Claude Code + Cursor, tool inventory, auth notes, docs links. This is what shows on https://www.npmjs.com/package/@commonly/mcp once we publish. No code changes. Doc-only. Unblocks any external developer trying to plug Claude Code / Cursor / Codex into a Commonly instance after Phase 4.
The npm org is `commonlyai` (the `commonly` org name was unavailable). Renaming the scope across package.json, src/index.js, README, and the integration doc to match what's actually published. Published as @commonlyai/mcp@0.1.0 on npm.
Tarball-leak defense. 0.1.0 accidentally shipped with a `.npmrc.tmp`
containing an auth token (npm secret-scanner caught + revoked the token
within minutes). Root cause: `npm publish` packs everything in the
package directory unless a `files` whitelist or `.npmignore` restricts it.
This commit:
- Adds `files: ["src","README.md","package.json"]` whitelist so only those
paths land in the tarball. Tests, .npmrc, .DS_Store, etc. cannot leak.
- Bumps version 0.1.0 → 0.1.1. 0.1.0 was unpublished but npm enforces a
24h republish cooldown on the same version string.
Verified via `npm pack`: tarball contains exactly 5 files
(package.json, README.md, src/{client,index,tools}.js). No .npmrc, no
tests, no other junk.
Future publishes: keep the auth `.npmrc` OUTSIDE the package dir
(`/tmp/.npmrc-<scope>` with `--userconfig=`), never inside.
…pdate Tier 2 follow-up to ADR-012 Phase 4 closure (PR #309's Tier 1 was the operator integration guide + package README). - **ADR-012 §11** — new "Phase 4 amendment" section. Records the self-review rejection of the original "always-on prefix injection" plan, the reference-platform survey (Anthropic memory tool, Letta/ MemGPT, mem0, MCP reference memory server, Hermes) that informed the cue + tool decision, and what actually shipped. Also adds a revision-history entry for 2026-05-10 and rewrites §Phasing's Phase 4 entry to match the shipped scope. - **ADR-010** — tool inventory updated (14 → 16). `commonly_save_my_memory` and `commonly_log_cycle` added to the table with route mappings and ADR-012 cross-refs. Distribution note clarifies the @Commonly → @commonlyai org scope rename + 0.1.1 npm publish. - **docs/agents/AGENT_RUNTIME.md** — Memory contract section now documents the cue + tool architecture: both `POST /memory/sync` and the equivalent tool surfaces, the §11 memory-changed cue (when / why / what it looks like), and an explicit note that digest fields are structured metadata for runtimes that want them, not always-on prefix dumps. - **docs/agents/COMMONLY_MCP.md** — scope rename + npm install instructions + 2-row addition to the tool reference table. - **CLAUDE.md** — `@commonly/mcp` → `@commonlyai/mcp` plus a pointer to docs/MCP_INTEGRATION.md from the ADR-010 index entry. No code changes. Self-reviewed: re-read each diff, cross-checked references against shipped code (commit fd9926c), and caught one stale CLAUDE.md ref to the old scope.
samxu01
added a commit
that referenced
this pull request
May 11, 2026
…ents, package publish (#309) Wraps up the documentation + distribution work for ADR-012 Phase 4 (cue + tool, MCP unification — code shipped in commonly#308 / fd9926c). **Operator-facing:** - `docs/MCP_INTEGRATION.md` — walkthrough for connecting Claude Code, Cursor, and Codex (via wrapper) to a Commonly instance via MCP. Covers token provisioning, install via `@commonlyai/mcp`, wire-up snippets, the 16-tool inventory, auth notes, troubleshooting. - `commonly-mcp/README.md` — npm-page-facing README for the published package. **Package distribution:** - `@commonlyai/mcp@0.1.1` published to npm (the `@commonly` scope was unavailable; we own `@commonlyai`). `package.json` adds a `files` whitelist so future tarballs only ship `src/`, `README.md`, and `package.json` — defense-in-depth after the 0.1.0 incident where a tmp `.npmrc` containing an auth token got bundled into the published tarball (npm secret-scanner caught + revoked the token within minutes; 0.1.0 unpublished). **ADR + runtime docs:** - `ADR-012 §11` — Phase 4 amendment. Records the rejection of the always-on prefix-injection plan, the reference-platform survey (Anthropic memory tool, Letta/MemGPT, mem0, MCP reference memory server, Hermes) that informed the cue + tool decision, and what shipped. `§Phasing` Phase 4 entry rewritten to match. - `ADR-010` — tool inventory updated (14 → 16); distribution note on the @commonlyai scope + 0.1.1 publish. - `docs/agents/AGENT_RUNTIME.md` Memory contract — cycles append now documents the tools surface alongside raw HTTP, digest reframed as structured metadata, new "Memory-changed cue" subsection. - `docs/agents/COMMONLY_MCP.md` — scope rename + 2-row addition to the tool reference table. - `CLAUDE.md` — ADR-010 index entry refreshed (scope, tool count, pointer to MCP_INTEGRATION.md). No code changes beyond `commonly-mcp/src/index.js` package-name string and `package.json` (name, version, files whitelist). No deploy needed — backend already running fd9926c from #308. Self-reviewed: re-read every diff, cross-checked against shipped code, caught + fixed a stale `@commonly/mcp` reference in CLAUDE.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Squash-merged via local push as e038653 per repo merge convention. |
samxu01
pushed a commit
that referenced
this pull request
Aug 4, 2026
review-checklist.md opened with a "Lands with (pointer edits, same PR)" line naming four edits that were never in the diff — the doc introducing rule 7 (phantom cross-layer contract) shipped as one: a header promising that another file provides something, with nothing holding the two together. All four now exist: - docs/development/README.md — index rows for the checklist and the AX log - REVIEW.md — context-loading step 6 citing §7; two-checklists note above the author checklist, so the name collision is broken from both sides - CLAUDE.md — companion pointer beside the REVIEW.md required-reading line, plus an anchor for the AX audit - CLAUDE.md — the NO_REPLY correction. Main read "it will be sent verbatim", wrong since PR #785: a bare sentinel in substantive content is stripped as producer leakage; backticked/fenced mentions survive; suppression stays total-match. Verified against sanitizeAgentContent and its test file, not against the prose that described it. Also in the checklist: repair a mangled clause in rule 7, and record the outer-transport-fence mechanic that makes the §9 tests read correctly. AX entry 6 corrected. It concluded the cycles append was unreachable through the tool surface; commonly_log_cycle has owned that verb since ADR-012 Phase 4 (#308/#309), two months earlier. Re-probed both calls today — every fact in the entry holds, the conclusion did not. The real defect is narrower: the capability is owned by one tool and named by another, and the 400 names the payload it wants without naming the tool that can emit it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
lilyshen0722
added a commit
that referenced
this pull request
Aug 4, 2026
* docs: ADR-016 + ADR-017 full drafts, reviewer checklist Replaces the ADR-016/017 stubs merged in #775 with the full drafts, and adds the incident-derived reviewer checklist assembled during milestone #11. ADR-016 (pod model and visibility) — kind x visibility tier x joinPolicy over the existing flags, no schema change. 7-state reachable enumeration, migration for the unrepresentable state, and an Enforcement gaps section verified against origin/main: 4 of 5 read surfaces consult the visibility tier; GET /api/agents/runtime/pods does not, and still returns latestSummary for non-member pods. ADR-017 (attention routing) — judge divergence + static irreversibility feeds, escalation envelope with required typed evidence, needs-you card with four lifecycle-visible faces, in-pod first. Budget sized against EEMUA/ISA-18.2 rates (source-verified, with the transfer caveat stated). docs/development/review-checklist.md — 13 reviewer rules, each carrying the incident that earned it. Both ADRs are Proposed, not Accepted; ratification is Sam's. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: ADR-016 — fix agent-admin reachable states, align joinPolicy migration Both from sprint-review's #792 pass, re-verified against origin/main: agent-admin is in NON_LISTABLE_POD_TYPES and refused by both visibility writers, so calling it a plain room overstated the enumeration — states 3-6 are unreachable for it. Adds a third derived kind (admin-room): terminally private like a DM, for a different reason (listability, not cardinality). Total reachable states 7 -> 8. Migration step 3 normalized null joinPolicy to invite-only while the schema and creation path default to 'open'. Corrected to 'open': the narrowing lives in the tier (self-joinable <=> community AND open), so a private pod with joinPolicy 'open' is still not self-joinable, and the migration should not be the one writer that disagrees with the schema. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: ADR-017 — authority boundary as primary trigger, per corpus labelling sprint-review labelled this pod's own unattended run (238 messages, four agents, four days): 15 warranted interrupting a human (6.3%), sustained 0.16/hr, peak 31/10min raw vs 5/10min filtered. The finding that changed the design: "escalate on irreversibility" caught zero of fifteen. The dominant class (8/15) is not misbehaviour at all — an agent correctly finishing and hitting a wall only the human can pass. So the primary trigger is structural, not behavioural: has this agent reached a boundary it cannot cross? The system already knows, because the boundary is the permission set — a query, not an inference, and it covers the largest class with no model. - new Layer 0 recording the corpus, the four observed classes ranked, and the caveat (n=15, one pod, one decision-maker) - authority boundary promoted to primary feed, with evidence typed as { boundary, artifact, availableTransitions } so cards name the decision - irreversibility kept as a safety net, with its zero-fire record stated: unbounded false-negative cost, bounded false-positive cost - envelope feed/class enums updated to the observed taxonomy Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: AX audit log + sharpen ADR-017's irreversibility caveat The zero-irreversibility caveat now states the labeller's own distinction: this corpus had no delete/spend/send permissions in play, so the zero is strong evidence that irreversibility is the wrong PRIMARY trigger and weak evidence about its firing rate where agents hold destructive capability. The zero measures the permission profile, not the mechanism's worth. Adds docs/development/agent-experience-audit.md — the AX findings Sam asked the sprint agents for, which were accumulating only in pod chat. Four entries: the docstring is the interface; permitted verdicts are undiscoverable until refused; silent success and silent failure look identical; pod prose is not delivery. Recurring shape: an agent's model of the system comes almost entirely from names, docstrings and error messages. Where those lie or stay silent, it forms a confident wrong model — with no visual channel to correct it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: bidirectional attention channel, #793 verified, AX entry 5 ADR-017 gains "the channel is bidirectional" — the missing inverse of everything else in it. Routing so far is agent -> human; the 2026-08-01 incident is system -> agent: the disclosure was fixed, merged, deployed and verified, and the pod was never told, so four agents kept planning around an exposure closed an hour earlier. Recorded as a principle, not a mechanism: an invalidation is not an escalation (the trigger is "a fact you relied on changed", which is observed class 3 pointed the other way — one mechanism, two directions), and its cost is silent and asymmetric (a missed escalation stalls one agent visibly; a missed invalidation leaves every agent producing correct-looking work over a dead premise). Explicitly do NOT build a subscription system: n=1 is not a mandate for a dependency graph. Notes that `basis` is already this signal read from the other end. ADR-016's enforcement-gap table updated against origin/main: #793 closed the gap by composing COMMONLY_LISTING_QUERY with the caller's authorized pods. Residual divergence recorded — it uses the flags-only fragment, not communityDiscoverQuery, so invite-only listed pods appear on the agent surface while excluded from the human one. Not a leak (all publicRead), but the route's own comment claims it cannot drift, and it still differs. AX audit: entry 5 (nothing tells an agent its premise expired), entry 1 marked closed by #793. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: ADR-016 — surface parity is the rule, H5 is the exception-point ux-lead's design call on the #793 residual, replacing the either/or I left open. The agent discovery surface adopts communityDiscoverQuery rather than the flags-only fragment: a comment asserting parity over a query that diverges is a phantom-contract seedling watering itself. The "agents should see request-access-able rooms" case is real but is the H5 case, and the 2026-07-29 dead-end ruling applies to agents equally — a discoverable row with no available action yields a 403 whose only use is relaying confusion, and that 403 is not machine-readable as "requestable later" either. Rule recorded: divergence between the human and agent visibility surfaces must be a decision with an affordance attached, never a side effect of which query constant a route imported. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: ADR-016 — parity is per-clause; "adopt the builder" was wrong sprint-review caught a defect in the rule committed one commit earlier. "Adopt communityDiscoverQuery on the agent route" treats three clauses as one decision; only the joinPolicy clause belongs there. - listing flags: shared (the visibility tier itself) - joinPolicy $ne invite-only: adopt — a row with no available action is a dead end for either reader, and the 403 isn't machine-readable as "requestable later" - members $ne callerId: never — the surfaces have different jobs, and it is subtly unsafe here: the route's second $or branch keys on installations, not membership, so a pod the agent is a member of without an active installation would be excluded by the clause and not restored by the branch Shared unit is therefore a fragment (flags + joinPolicy) that both surfaces compose, each adding its own caller clause — the same lesson as the original fragment/builder split, one level down. Urgency recorded as none: 3 community-listed pods, 0 invite-only, so the divergence is theoretical and a test would pass vacuously today. Revisit trigger is H5 landing, when joinPolicy drops from both surfaces together. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: ADR-017 — fix seven inconsistencies from the end-to-end read sprint-review's full pass (PR #792 review 7) found seven locally-correct edits that had stopped agreeing with each other. All were introduced by incremental rewrites and none were caught by incremental review. 1. Judge's class enum conflated two taxonomies. The judge cannot detect authority-boundary or deadlock — those come from the no-model query feed. Judge now emits divergenceClass (scope-expansion, target-change, abandonment, other); the envelope's top-level class carries the observed taxonomy, with a comment stating they are never merged. 2. "Both feeds" / "two feeds" -> three feeds, four routing inputs. 3. Ratification point 3 asked Sam to ratify a "four-class taxonomy" that no longer exists. Now names both taxonomies explicitly. 4. Override statistic appeared as both 49-96% (pre-verification) and 46-96% (verified). Unified on the verified figure. 5. "Two-tier staleness rule:" lead-in survived the unification that replaced it with one rule. 6. "Latest human word wins" contradicted "re-binding is ordinary agent behavior". The latter is correct and verified in code; corrected to ordering-not-identity, with an explicit warning never to write a human-only gate since no issuer field exists to build it on. 7. Deadlock listed under class-1 instances; it is class 4. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ax): entry 6 — a documented call shape the tool cannot express The heartbeat instruction directs agents to append cycle takeaways via commonly_save_my_memory with a nested { append: { content } } payload. The deployed tool schema accepts only content (string) or entries (array) with additionalProperties: false, so no reachable argument shape produces it; all three forms 400 with the server naming a payload the tool cannot emit. `cycles` is also absent from the tool's own documented section list. Three surfaces describe the same capability differently — scheduler instruction, tool schema, server validator — and only the last is authoritative. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ax): entry 7 — directives and arguments share one identity The orchestrating assistant posts under the operator's account, so "take #795 next" and "here is my read of the taint path" arrive in one voice. Agents defaulted to treating both as directives, which is correct when they cannot be told apart — and a technical claim propagated two review cycles unchecked, then landed misattributed in a PR approval that is now the durable record of a design choice. A directive should be followed; an argument should be checked. Identity is the only signal an agent has, so where one identity carries both, the weaker treatment wins by default. Interim protocol recorded pending per-seat identities (#791). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ax): entry 7 — correct its own byline, record the cascade The entry about misattribution-through-shared-identity was itself misattributed: filed crediting ux-lead, who declined it. The content came from the orchestrating assistant posting under the operator account (52211). sprint-review's log check found the full cascade: 52204 (operator account) -> credited to pod-architect -> declined -> re-credited in a PR approval because the declination never arrived -> refiled here against a third wrong seat. Four misattributions in one incident, among participants actively trying to attribute correctly, one inside the document describing the problem. Corrected, the entry is self-demonstrating rather than self-refuting: no amount of diligence substitutes for a distinguishable identity. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: land the four pointer edits the checklist header promised review-checklist.md opened with a "Lands with (pointer edits, same PR)" line naming four edits that were never in the diff — the doc introducing rule 7 (phantom cross-layer contract) shipped as one: a header promising that another file provides something, with nothing holding the two together. All four now exist: - docs/development/README.md — index rows for the checklist and the AX log - REVIEW.md — context-loading step 6 citing §7; two-checklists note above the author checklist, so the name collision is broken from both sides - CLAUDE.md — companion pointer beside the REVIEW.md required-reading line, plus an anchor for the AX audit - CLAUDE.md — the NO_REPLY correction. Main read "it will be sent verbatim", wrong since PR #785: a bare sentinel in substantive content is stripped as producer leakage; backticked/fenced mentions survive; suppression stays total-match. Verified against sanitizeAgentContent and its test file, not against the prose that described it. Also in the checklist: repair a mangled clause in rule 7, and record the outer-transport-fence mechanic that makes the §9 tests read correctly. AX entry 6 corrected. It concluded the cycles append was unreachable through the tool surface; commonly_log_cycle has owned that verb since ADR-012 Phase 4 (#308/#309), two months earlier. Re-probed both calls today — every fact in the entry holds, the conclusion did not. The real defect is narrower: the capability is owned by one tool and named by another, and the 400 names the payload it wants without naming the tool that can emit it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships the Tier 1 follow-up to ADR-012 Phase 4 — makes the MCP server actually usable by external developers:
No runtime/code changes beyond the package-name string in `commonly-mcp/src/index.js` (the value reported by the server identity handshake).
Why now
Phase 4 closed the read+write+cue loop on dev, but anyone outside the monorepo had no path to plug Claude Code or Cursor into a Commonly instance. With this:
```bash
claude mcp add commonly \
-e COMMONLY_API_URL=https://api-dev.commonly.me \
-e COMMONLY_AGENT_TOKEN=cm_agent_xxx \
-- npx -y @commonlyai/mcp
```
…and you have all 16 `commonly_*` tools in a Claude Code session.
Test plan
What's NOT in this PR
Tier 2 ADR updates (ADR-012 Phase 4 amendment, ADR-010 tool-inventory update, AGENT_RUNTIME.md memory contract section) and skill updates — separate small follow-up PR.
🤖 Generated with Claude Code