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	13474
title	Add retention caps to MCP server logs
state	Closed
labels	enhancementaiarchitectureperformancemodel-experience
assignees	neo-gpt
createdAt	Jun 18, 2026, 5:04 PM
updatedAt	Jun 19, 2026, 2:11 AM
githubUrl	https://github.com/neomjs/neo/issues/13474
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 19, 2026, 2:11 AM

Add retention caps to MCP server logs

Closed v13.1.0/archive-v13-1-0-chunk-3 enhancementaiarchitectureperformancemodel-experience

neo-gpt commented on Jun 18, 2026, 5:04 PM

Context

Release classification: boardless operational hardening; this is not a v13 release blocker.

A 2026-06-18 stability sweep found the local Agent OS healthy, but .neo-ai-data/logs had grown to 211M. Long-lived desktop harnesses can keep several MCP server instances running for many hours, and the shared daily log files currently have no repository-owned retention cap.

Verification before filing:

Live latest-open sweep: checked latest 20 open issues at 2026-06-18T15:04:02Z; no equivalent open issue found.
Targeted GitHub duplicate sweep: MCP server log retention log cap daily logs returned no open matches.
A2A in-flight sweep: checked recent 30 messages; no overlapping lane claim found.
KB/local sweep: #10582 intentionally added always-on Memory Core and Neural Link file logs and explicitly left disk-bloat protection to per-deployment retention policy. #11878 established the shared logger primitive, but no active ticket covers retention caps.

The Problem

Daily filename rotation is not retention. It prevents one file from growing forever, but the log directory still grows without bound across days and across multiple MCP server instances.

That is acceptable only if every deployment supplies external logrotate/systemd/docker retention. The local Agent OS and desktop harness setup do not have that guarantee, and recent evidence shows the directory can become noisy enough to make diagnostics harder.

The Architectural Reality

ai/mcp/server/shared/logger.mjs owns the shared MCP logger/file-sink behavior.
Per-server MCP config templates wire file logging through shared defaults and aiConfig.logPath.
Prior work established always-on file sinks for observability (#10582) and shared logger consistency (#11878), but retention was deliberately deferred.
Neo already has precedent for config-owned retention in other agent data stores; retention should be explicit substrate, not an operator-only cleanup habit.

The Fix

Add config-driven retention for MCP server file logs at the shared logger layer:

Introduce logger retention settings for daily log files, such as max age and/or max retained files.
Apply retention only to files matching the active logger prefix in the configured log directory.
Never delete the currently active daily file.
Run pruning at a bounded point such as logger initialization or day rollover, not on every log write.
Add focused tests with a temp log directory proving matching old files are pruned and unrelated files/current-day files are preserved.
Surface the config defaults in the relevant MCP server config templates.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
Shared MCP logger file sink	`ai/mcp/server/shared/logger.mjs`	Daily log files are still written as today, but old matching files are pruned according to config.	If pruning fails, logging continues and emits a bounded warning instead of crashing the MCP server.	JSDoc/config comments for retention keys.	Unit test with temp files covering prune and preserve cases.
MCP server logger config	Per-server MCP config templates	Operators can tune or disable retention per deployment through config/env-backed leaves.	Missing config uses conservative defaults; invalid values fall back safely.	Config template comments.	Config-level test or focused unit coverage for default normalization.

Decision Record impact

None. This amends diagnostics durability around an existing logging surface without changing MCP protocols or server ownership boundaries.

Acceptance Criteria

MCP server file logs have a config-driven retention cap by age and/or retained-file count.
Retention applies only to matching MCP log files in the configured log directory.
The active current-day log file is never pruned by the retention pass.
Pruning failures are non-fatal and produce a bounded warning.
Focused tests cover old matching logs pruned, unrelated files preserved, active file preserved, and disabled/invalid config behavior.
Relevant MCP config templates expose the retention leaves with documented defaults.

Out of Scope

Fixing individual oversized log call sites such as Neural Link bridge payload dumps.
Deleting existing local logs manually.
Changing Neural Link action recorder storage retention.
Introducing a third-party log rotation framework.
Relying on OS-specific logrotate/systemd/docker retention as the only solution.

#10582 — always-on Memory Core and Neural Link file sinks; retention explicitly out of scope.
#11878 — shared MCP logger primitive.
#13473 — sibling ticket for the Neural Link full bridge payload log line.

Origin Session ID: ef8b263f-1cdc-431a-a730-2c6c2ff26f98

Retrieval Hint: "MCP shared logger daily file retention cap .neo-ai-data logs no infinite growth"