Repository navigation
MCP: expose existing agent memory and learning/correction workflows as tools #64
Description
The existing graph MCP server does not expose the memory and learning/correction workflows already available in terraphim-agent. Kilo and other MCP clients therefore cannot perform those workflows through the server; installing the corresponding instruction skills does not add MCP tools.
Evidence and scope
- Current MCP source at
acd1515a452dmanually registers 26 tools; none exposes agent memory capture/readback or learning/correction/compile/export. - The released
terraphim_mcp_server-v1.21.18-rc.1was also inspected and executed during marketplace qualification. Its graph/RLM tools are distinct from dedicated memory/learning tools. - Released
terraphim-agent1.21.20 has been executed against isolated real stores: memory capture and ID-based readback preserve content/tag; a real failed command and its successful correction are retained; annotating a failure alone compiles zero rules; adding an explicit correction compiles one mapping and exports a Markdown note containingsynonyms::. - Kilo 7.8.8 loaded the four installed Terraphim skills successfully. That is instruction loading, not evidence that these missing MCP endpoints exist.
Implement the missing surface in the existing Rust MCP server, reusing Terraphim's existing agent, memory, learning, persistence and synonym types/crates. Extract shared application logic if necessary; do not duplicate stores or add a shell-string wrapper around the CLI. Tool names and the final contract should be agreed during design.
Acceptance criteria
- Typed MCP tools expose existing memory capture, ID-based readback and supported list/query operations, with actual saved IDs, content and provenance tags in results.
- Typed tools expose learning capture/query/correction and the separate explicit correction-add, compile and KG-export operations supported by the existing agent. Capturing an error or annotating a correction must not silently activate a hook or execute a command.
-
tools/listadvertises complete validated input/output contracts and accurate read/write annotations. Invalid inputs, unknown IDs and failed persistence return actionable errors rather than success-shaped results. - Storage scope is explicit. Return the effective scope/location where appropriate; enforce configured boundaries and document environment-variable precedence. A project working directory alone must not be represented as memory isolation.
- Reuse existing
synonyms::syntax, normalization and KG types. Compilation/export must contain the actual authored original-to-corrected mapping. - Real integration tests launch the server through MCP and use isolated persistent stores: capture → read by returned ID → server restart → read again; CLI/MCP interoperability reads the same stored records.
- Real learning tests retain failed-command exit/stderr and separately executed corrected output. Prove annotation-only compile = 0, explicit correction compile = 1, and inspect the saved JSON and
synonyms::Markdown. Do not substitute submitted input, model summaries or mocked tool results for output evidence. - Test mutation boundaries, path traversal, configured-scope isolation, concurrent calls and meaningful cancellation/failure behavior. No writes to the developer's normal memory store in tests.
- Publish the updated server through existing CI/CD; download the released package and verify these tools in an actual Kilo/MCP host, preserving saved outputs and package identities.
- Update server README, plugin notes, Skills/Kilo descriptions and runnable examples only after released-host checks pass. Add a short demo showing actual memory readback and the explicit correction/compile/export sequence.
Related work
- Kilo skills submission: distribution of instructions, separate from this missing server capability.
- Graph synonym-search defect #62 and unknown-role autocomplete defect #63 remain separate defects; this issue does not close them.
No automatic hook installation/activation, generic arbitrary-command execution tool, new memory backend or Zed application-fork change is required by this issue.
Activity
test(release): align producer contract with 1.21.21 (Refs #64)
AlexMikhalev commentedon Oct 15, 2026
Implementation is in PR #66. The server opts into nine typed local agent tools only with an explicit absolute
--agent-data-dir, and the updated CLI shares the same atomic store and writer locks.Actual process tests cover memory capture/show/restart and CLI readback, real failure capture, annotation-only compilation with zero rules, an explicit correction producing one saved mapping, and
synonyms::note export. Compilation/export do not activate hooks or register a role graph. Invalid, corrupt, busy and unrepresentable inputs fail before destination replacement.The independently reviewed source passed 23 fresh shared-store and MCP protocol tests at version 1.21.21. The immutable client staging workflow is running; the PR's exact package-hash gate will be satisfied from those sealed bytes before final CI/merge/public promotion. This is implementation and staging progress, not a released-binary or native Kilo completion claim.
PR: #66
Stage-only CI: https://github.com/terraphim/terraphim-clients/actions/runs/38711156306
fix(ci): qualify sealed Arch sources before promotion (Refs #64)
fix(ci): retain Arch readbacks through one container path (Refs #64)
fix(agent): release transaction locks before inherited descriptors cl…
chore(release): prepare corrected clients 1.21.22 (Refs #64)
feat: expose explicit local agent memory and learning MCP tools (#66)
AlexMikhalev commentedon Oct 15, 2026
Implemented in normally merged PR #66 and published in Rust MCP 1.21.22-rc.1, paired with terraphim-agent 1.21.22.
The nine tools are opt-in for stdio through an explicit absolute
--agent-data-dir: memory capture/show/list, learning capture/query/correct, and correction add/compile/export. Without that argument they are absent; the directory is refused for SSE. The server reuses the existing Terraphim memory/learning types and shared storage implementation. It does not execute a command, activate a hook, or register exported Markdown automatically.Actual downloaded release verification passed:
synonyms::Markdown.88a09d8b11e4eab550c6f7410f86faee7cc41ecc; MCP merged sourcee1cd8e00097354268fa11312c0f7fe71614ee218).The failed 1.21.21 candidate was withheld. The inherited-descriptor lock fix has deterministic real fork/descriptor regressions and passing full Linux CI. The new binaries were checked against public checksums; no source-built product binary substituted for the released package. This verification covers the CLI/MCP contracts, not Kilo native UI or automatic learning activation.
AlexMikhalev commentedon Oct 15, 2026
Verification refinement: review found that the earlier test executed a separate
printfargv while recording a differently escaped shell replacement. That earlier run proved persistence and locking, but did not prove execution of the exact stored correction.The test now reads the replacement from the actual compiled thesaurus and executes that exact string (
printf '%s\n' 'reviewed correction'). Fresh runs against the unchanged public agent 1.21.22 / MCP 1.21.22-rc.1 packages pass on macOS ARM64 and isolated Linux ARM64; both return and save exactlyreviewed correctionfollowed by one newline (hex726576696577656420636f7272656374696f6e0a). Independent review reran all six macOS agent contracts. The test-only source correction is being merged through normal CI; no product binary or immutable release tag was changed. Compiled rules still require explicit activation, and exported KG notes remain unregistered until separately loaded.