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	11923
title	Clean KB and graph source-comment archaeology
state	Closed
labels	documentationenhancementairefactoringarchitecturemodel-experience
assignees	neo-gpt
createdAt	May 24, 2026, 10:48 PM
updatedAt	Jun 7, 2026, 7:15 PM
githubUrl	https://github.com/neomjs/neo/issues/11923
author	neo-gpt
commentsCount	0
parentIssue	11912
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 25, 2026, 7:22 AM

Clean KB and graph source-comment archaeology

Closed v13.0.0/archive-v13-0-0-chunk-13 documentationenhancementairefactoringarchitecturemodel-experience

neo-gpt commented on May 24, 2026, 10:48 PM

Parent epic: #11912

Context

#11912 is being reshaped into an epic with grouped cleanup subissues. This subissue owns the Knowledge Base, Graph, and ingestion-service source-comment group.

Current grouped baseline on origin/dev:

ai/services/knowledge-base/**/*.mjs: 113 diagnostic matches.
ai/services/graph/**/*.mjs plus ai/graph/**/*.mjs: 41 diagnostic matches.
ai/mcp/server/knowledge-base/**/*.mjs: 16 diagnostic matches.
ai/services/ingestion/**/*.mjs appears in the residual high-noise list and belongs with this Brain-data-service group.

The Problem

Knowledge Base and Graph comments often encode implementation history rather than durable ingestion, embedding, graph, and Golden Path contracts. That makes living code read like a PR transcript and trains reviewers to accept the same pattern.

The Architectural Reality

This group is the Brain data substrate: KB ingestion, vector provider selection, document lifecycle, graph inference, Golden Path synthesis, identity roots, and ingestion bridges. The cleanup must preserve why a projection, metric, or graph edge exists while moving away from ticket/AC/cycle phrasing.

The Fix

Clean KB, Graph, and ingestion source comments in grouped batches:

Rewrite historical anchors into durable service contracts and stable symbol references.
Keep comments that explain non-obvious graph/embedding invariants, but remove or re-home PR archaeology.
Separate runtime/test/schema changes into their own tickets if discovered.
Provide before/after counts per PR.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
KB service comments/JSDoc	#11912 source-comment cleanup epic	Comments explain ingestion/provider/storage contracts, not ticket chronology	Stable docs may receive load-bearing rationale if source would become too long	PR bodies	Before/after focused diagnostics
Graph/identity comments/JSDoc	#11912 source-comment cleanup epic	Comments explain graph-edge semantics and synthesis boundaries in stable terms	File separate bug/substrate ticket if cleanup exposes a contract mismatch	PR bodies	Before/after focused diagnostics
Ingestion bridge comments/JSDoc	#11912 source-comment cleanup epic	Comments explain handoff contracts between Memory/KB/Graph surfaces	Defer non-`.mjs` generated surfaces	PR bodies	Before/after focused diagnostics

Decision Record Impact

Aligned with ADR 0005 and ADR 0008. No ADR amendment expected.

Acceptance Criteria

Clean ai/services/knowledge-base/**/*.mjs comments/JSDoc to durable intent phrasing.
Clean ai/services/graph/**/*.mjs and ai/graph/**/*.mjs comments/JSDoc to durable intent phrasing.
Clean relevant ai/services/ingestion/**/*.mjs comments/JSDoc under the same rule.
PR evidence includes before/after focused counts and git diff --check.
Parent #11912 remains open until all grouped subissues are complete.

Out of Scope

Memory Core, GitHub Workflow, daemon/script, and residual config groups.
Runtime behavior changes.
Rewriting issue/PR/discussion history.

Parent epic: #11912

Origin Session ID: 019e5bac-15f3-7830-a59c-72772c757f9a

Handoff Retrieval Hint: query_raw_memories("11912 knowledge-base graph ingestion source-comment archaeology")

tobiu referenced in commit 9838b80 - "chore(ai): clean kb service source comments (#11923) (#11931) on May 24, 2026, 11:38 PM

tobiu referenced in commit 4a1d9cb - "chore(ai): clean graph service source comments (#11923) (#11932) on May 24, 2026, 11:38 PM

tobiu referenced in commit a68d438 - "chore(ai): clean graph core source comments (#11923) (#11933) on May 24, 2026, 11:39 PM

tobiu referenced in commit d2d9c06 - "chore(ai): clean ingestion source comments (#11923) (#11936) on May 25, 2026, 12:39 AM

tobiu referenced in commit 37e2d4c - "chore(ai): clean kb mcp source comments (#11923) (#11943) on May 25, 2026, 7:22 AM

tobiu closed this issue on May 25, 2026, 7:22 AM