Skip to content

docs(arch): §22c AgentKeys app surface (CLI + web UI + daemon)#135

Merged
hanwencheng merged 2 commits into
mainfrom
docs/agentkeys-app-arch
May 26, 2026
Merged

docs(arch): §22c AgentKeys app surface (CLI + web UI + daemon)#135
hanwencheng merged 2 commits into
mainfrom
docs/agentkeys-app-arch

Conversation

@hanwencheng
Copy link
Copy Markdown
Member

Summary

Adds a new §22c to docs/arch.md documenting the operator-facing AgentKeys app surface — CLI + web UI + daemon as one distribution, in the agentmemory shape iam.md §2.3 points at. Pure docs PR. No code changes.

Companion to the #110 issue comment synthesizing agentmemory's architecture into a phased M1→M4 web UI roadmap.

What §22c covers

Contradictions found + fixed in the same change

  1. §9 cold-start step 9 said "Daemon: persist J1_agent; enter MCP-stdio loop + sidecar proxy" — written before Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 made the MCP server its own surface. Now references §22c.1 for the surface separation; daemon hands off LLM-host integration via backend variant at startup.

  2. §22c.1's own stale cross-ref to "§22.Backend pluggable axis" — §22's six axes don't list MCP backend. Reworded inline to describe the backend choice (DaemonBackend / HttpBackend / InMemoryBackend) explicitly, without claiming a row in §22's table.

Why now

Test plan

  • arch.md TOC still threads §22 → §22a → §22b → §22c → §23 in order
  • All cross-refs in §22c.6 point at real anchors / real issues / real iam.md sections
  • No contradictions remain with §9, §10.3, §12, §22 (verified by grep)
  • Pure markdown change; no code / test impact

Anchors to verify locally:
```bash
grep -n '^## 22c\|^## 22b\|^## 23' docs/arch.md

Expect: 22b. → 22c. → 23. in order

```

🤖 Generated with Claude Code

Three contradictions/gaps in arch.md called out in #110 thread:

1. arch.md described agentkeys-mcp-server (after #107) but no section
   covered the broader operator-facing app surface — CLI + web UI +
   daemon as one distribution, in the agentmemory shape iam.md §2.3
   points at. Result: no canonical home for vendor onboarding, device
   pairing, backend wiring concepts that are now post-#107 priorities.

2. §9 cold-start step 9 said daemon 'enter MCP-stdio loop + sidecar
   proxy' — written before #107 made the MCP server its own surface.
   Now references §22c.1 for the surface separation; daemon hands off
   LLM-host integration via backend variant at startup.

3. §22c.1 had a stale cross-ref to '§22.Backend pluggable axis' that
   doesn't exist — §22's six axes don't list MCP backend. Reworded to
   describe backend choice (DaemonBackend / HttpBackend / InMemoryBackend)
   inline without the bad reference.

New §22c covers:
- 22c.1 three surfaces (CLI + web + MCP server) on one daemon
- 22c.2 four backend kinds (hosted LLM / local LLM / task agent / chat
  agent) — wires the per-runtime trust path
- 22c.3 multi-device master pairing UX (the missing layer on top of
  §10.3.1 cryptographic flow — phone + desktop as masters)
- 22c.4 vendor device pairing (xiaozhi MagicLick / Doubao / etc.) —
  closes the no-auth gap from #107's stage-1 demo
- 22c.5 what the daemon does NOT become (clarifies trust boundary
  against any temptation to put runtimes in the daemon)
- 22c.6 cross-references to #110 / #133 / #134 + iam.md §4.4

Companion to the #110 issue comment that synthesizes agentmemory's
architecture into a phased M1→M4 web UI roadmap.
Captures the three projects whose architectures informed §22c, each
with a clear what-we-borrow / what-we-don't note:

- agentmemory: shape (CLI + daemon + web), already mirrored in §22c.1
- iii: Trigger taxonomy as internal dispatch vocabulary for #133's
  agentkeys hook subcommand; NOT the runtime (worker registry breaks
  our per-data-class isolation; Elastic License 2.0 limits derivative
  deployment)
- xiaozhi-mcphub: multi-MCP aggregation (the AggregateBackend variant
  we'd add to agentkeys-mcp-server in M4 if we ever need it, NOT an
  external JS/TS stack in the trust path)

Companion to the #133 comment that lays out the iii Trigger →
agentkeys hook handler mapping concretely.
@hanwencheng hanwencheng merged commit 45f0426 into main May 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant