What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13506
title	Add Memory Core MCP tool-call telemetry
state	Closed
labels	enhancementdeveloper-experienceaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 19, 2026, 5:30 AM
updatedAt	Jun 19, 2026, 10:00 AM
githubUrl	https://github.com/neomjs/neo/issues/13506
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 19, 2026, 10:00 AM

Add Memory Core MCP tool-call telemetry

Closed v13.1.0/archive-v13-1-0-chunk-4 enhancementdeveloper-experienceaiarchitecturemodel-experience

neo-gpt commented on Jun 19, 2026, 5:30 AM

Context

While sweeping Agent OS stability / diagnostics / self-healing debt for dogfooding-scale deployments, the Memory Core API guide surfaced an unfulfilled monitoring contract: learn/agentos/tooling/MemoryCoreMcpApi.md still says Memory Core should log tool calls with timing information and track query / summarization metrics (lines 213-217).

V-B-A found that the sibling servers already have durable recorder patterns, but Memory Core does not:

ai/services/knowledge-base/KBRecorderService.mjs:44-89 creates kb_query_log with tool, success, and duration_ms.
ai/mcp/server/knowledge-base/toolService.mjs:76-104 wraps every KB MCP tool call and records success/failure timing in finally.
ai/services/neural-link/RecorderService.mjs:10-75 persists Neural Link tool invocation telemetry to nl_action_log.
ai/mcp/server/BaseServer.mjs:353-385 already captures t0 for all callTool dispatches and exposes onHealthGateFailure with that timestamp (lines 245-254, 375-378).
ai/mcp/server/memory-core/toolService.mjs:61-63 currently exports the raw ToolService.callTool binding with no recorder wrapper.

Release classification: boardless dogfooding hardening. This improves cloud / long-running diagnostics, but is not a v13 release blocker.

Live latest-open sweep: checked latest 20 open issues immediately before filing on 2026-06-19 05:29 CEST; no equivalent Memory Core tool-call telemetry ticket found. Recent A2A sweep: checked latest 30 all-state messages; no overlapping [lane-claim] / [lane-intent] on this scope found.

The Problem

When Memory Core stalls, rejects a call through the health gate, or returns degraded query results, operators and agents currently have to infer behavior from live harness symptoms, generic logs, or specific feature diagnostics. We do not have a durable per-tool timing/failure ledger for the Memory Core MCP surface itself.

That matters more in remote/shared deployments: multiple agents can use the same Memory Core for weeks, failures can be intermittent, and a single healthcheck snapshot does not answer questions like:

Which Memory Core tools are slow or failing most often?
Are failures concentrated in query_raw_memories, query_summaries, add_memory, mailbox tools, or health-gated tools?
Did a health-gate failure happen before service dispatch, and how long did the rejected call wait?
Are query diagnostics backed by a durable trend rather than one current probe?

The Architectural Reality

Memory Core is not Knowledge Base. Its tool arguments can include full prompts, thoughts, responses, A2A message bodies, and private operational context. Copying KB's full args / result recorder shape blindly would duplicate sensitive Memory Core payloads and increase database/log growth.

The correct sibling lift is the recorder architecture, not the full payload policy:

Use Memory Core's service layer as the owner, likely ai/services/memory-core/*RecorderService.mjs.
Initialize it from the Memory Core server boot path, next to the existing service dependencies.
Wrap Memory Core toolService.callTool in the MCP server layer, mirroring the KB finally pattern.
Reuse BaseServer's t0/onHealthGateFailure seam for pre-dispatch health-gate rejects.
Store bounded metadata, not raw Memory Core payloads.

Pre-Flight (structural fast-path): a future ai/services/memory-core/*RecorderService.mjs matches the sibling recorder pattern of ai/services/knowledge-base/KBRecorderService.mjs and ai/services/neural-link/RecorderService.mjs; no novel directory choice.

The Fix

Add a best-effort Memory Core MCP telemetry recorder that records one row per Memory Core MCP tool call with bounded operational metadata:

tool
timestamp
caller identity / tenant context where available
session_id where available
success
duration_ms
failure_stage (health_gate, dispatch, policy, etc.)
bounded error_code / error_message
payload sizes or redacted shape metadata instead of raw args / result

Expose the data through an on-demand aggregate surface rather than the hot-path healthcheck. A narrow aggregate such as get_memory_core_tool_metrics or an equivalent diagnostic service/script should return rolling counts, failures, and latency buckets by tool without exposing raw memory/message content.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Memory Core recorder service	Sibling recorder services in Knowledge Base / Neural Link	Best-effort singleton service initializes a SQLite table in the shared Memory Core database and never throws into tool execution	If SQLite is unavailable or locked, skip telemetry and log a bounded warning	JSDoc on the service; update Memory Core MCP API monitoring section	Unit test initializes schema and verifies logging is non-throwing
Memory Core `toolService.callTool` wrapper	`ai/mcp/server/knowledge-base/toolService.mjs:76-104`	Wrap successful and failed dispatches in `finally`, recording `tool`, `success`, `duration_ms`, bounded failure metadata	Tool behavior unchanged if recorder disabled	Inline JSDoc / comment explaining redacted payload policy	Unit test for success and thrown service dispatch
Health-gate failure telemetry	`BaseServer.onHealthGateFailure({toolName,args,error,t0})`	Memory Core overrides the hook to record rejected calls with `failure_stage: 'health_gate'`	Existing `formatHealthError` response remains unchanged	Server JSDoc	Unit test invokes hook with a fake error and asserts bounded row
Aggregate diagnostic surface	Existing on-demand diagnostics pattern (`get_sqlite_holder_diagnostics`, Chroma/graph reports)	Return aggregated per-tool counts/failures/latency without raw args/results	If telemetry table missing, return empty aggregate + explanatory status	OpenAPI schema if MCP tool; script usage if CLI	Unit test verifies aggregate shape and no raw payload leakage
Payload redaction policy	Memory Core owns sensitive prompts/messages	Store payload sizes, tool name, and bounded errors; do not persist raw `prompt`, `thought`, `response`, `body`, or raw result JSON	If a future raw-debug mode is needed, gate it behind explicit config and caps in a separate ticket	Service JSDoc + docs note	Unit test with sentinel secret proves it is absent from stored telemetry

Decision Record impact

Aligned with existing Agent OS observability patterns. No ADR change required: this is a sibling recorder service and on-demand diagnostics surface, not a new deployment topology or healthcheck contract.

Acceptance Criteria

Memory Core has a best-effort recorder service under the Memory Core service layer with schema/indexes for per-tool operational telemetry.
Memory Core MCP tool dispatch records successful calls, thrown dispatch failures, policy refusals, and health-gate rejects with duration_ms.
Recorder rows do not persist raw Memory Core payloads or raw result JSON; sentinel coverage proves sensitive text is absent.
An on-demand aggregate surface exposes per-tool counts, failures, and latency summaries without bloating healthcheck.
Tests cover success, dispatch failure, health-gate failure, recorder-unavailable fallback, and redaction.
learn/agentos/tooling/MemoryCoreMcpApi.md is updated so the monitoring/logging section reflects the implemented contract rather than future tense.

Out of Scope

Adding raw request/response audit logging for Memory Core tools.
Adding healthcheck fields for all telemetry metrics.
Solving any specific provider, Chroma, or summarization stall.
Changing Knowledge Base or Neural Link recorder schemas except for shared helper reuse if it is strictly mechanical.

Avoided Traps

Copying KB payload logging literally. KB query args are much less sensitive than Memory Core prompt / thought / response / A2A payloads. Memory Core must record operational telemetry, not duplicate content.
Putting aggregates in healthcheck. We already learned expensive operator-periodic observability belongs behind on-demand diagnostics, not the liveness hot path.
Treating this as a root-cause fix. This ticket improves evidence quality for the next stall; it does not claim to repair provider, Chroma, or summarization bugs.

Related: #13475
Related: #13480
Related: #13503
Related: #12065

Origin Session ID: c3a6e312-b858-4be4-ad97-9bc55cbad5ae

Retrieval Hint: "Memory Core MCP tool-call telemetry KBRecorderService duration_ms health-gate failure redacted payload"