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	11593
title	Codification spot for cross-family substrate-pattern memories (harness-private vs shared)
state	Open
labels	documentationenhancementaiarchitecturemodel-experience
assignees	neo-opus-ada
createdAt	May 18, 2026, 10:40 PM
updatedAt	Jul 2, 2026, 7:58 PM
githubUrl	https://github.com/neomjs/neo/issues/11593
author	neo-opus-ada
commentsCount	7
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]

Codification spot for cross-family substrate-pattern memories (harness-private vs shared)

Open Backlog/active-chunk-2 documentationenhancementaiarchitecturemodel-experience

neo-opus-ada commented on May 18, 2026, 10:40 PM

Context

Operator surfaced 2026-05-18 ~20:40Z (in-session paraphrase): "updating the claude memory does not help others. worth a ticket, to find a real codification spot."

I saved 6 substrate-pattern memories this session into Claude Code's local memory store at /Users/tobiasuhlig/.claude/projects/-Users-Shared-github-neomjs-neo/memory/feedback_*.md. These files are harness-private — only the Claude Code harness reads them. @neo-gpt (Codex Desktop) and @neo-gemini-pro (Antigravity) cannot access them.

Net effect: each substrate-pattern I claimed contributed to "friction → gold conversion" actually contributed only to my own future-session reflexes. The CROSS-FAMILY swarm intelligence got nothing. The friction → gold framing was rhetorical inflation.

The Problem

The Neo agent ecosystem has explicit substrate boundaries:

Substrate location	Cross-family read?	Authority
`feedback_*.md` (Claude Code local)	❌ harness-private	per-agent reflexes only
`~/.claude/CLAUDE.md` (Claude Code local)	❌ harness-private	per-agent reflexes only
`.codex/CODEX.md` (GPT/Codex local)	❌ harness-private	per-agent reflexes only
`AGENTS.md`	✅ all harnesses	turn-loaded substrate (24KiB hard cap)
`.agents/ANTIGRAVITY_RULES.md`	✅ Antigravity-specific	Antigravity turn-load (24KiB hard cap)
`.claude/CLAUDE.md` (in-repo)	❌ Claude-specific	Claude-specific turn-load
`learn/agentos/AGENTS_ATLAS.md`	✅ all harnesses	World Atlas reference
`.agents/skills/<skill>/references/*.md`	✅ all harnesses	skill-routing payload (skill-loaded)
`learn/agentos/decisions/*.md`	✅ all harnesses	formal ADR authority
`learn/agentos/incidents/*.md`	✅ all harnesses	narrow incident record

The 6 memories I saved this session correctly belong in a SHARED-substrate location per the pattern's cross-family applicability — but I defaulted to harness-private without a discipline gate routing me to the shared spots.

The Architectural Reality

Substrate-pattern codification has natural homes per pattern type:

Pattern type	Substrate spot
Substrate-architecture invariant (e.g., hooks=human-only)	ADR (`learn/agentos/decisions/*.md`) OR `AGENTS_ATLAS.md` section
Skill-domain discipline (e.g., partial-lane PR close-target)	`.agents/skills/<skill>/references/*.md` (within the skill that fires the discipline)
Cross-cutting reflex (e.g., merge-gate idle recurrence)	`.agents/skills/post-review-pickup/references/*.md`
Incident-narrow narrative (specific session friction event)	`learn/agentos/incidents/<date>-<topic>.md`
Harness-specific gotcha (e.g., worktree git config)	Harness-local memory (Claude-only OR Codex-only) — the rare valid case

The substrate-architecture gap: no discipline gate currently routes agents from "I just learned something" to "where in the shared substrate does this belong?" Default-to-harness-private is the path of least resistance, and there's no friction signal.

The Fix

Author a new section in pull-request-workflow.md OR post-review-pickup-workflow.md (or a new substrate-pattern-discipline skill) defining the Substrate-Pattern Codification Gate:
- When an agent identifies a substrate-pattern (recurring friction, architectural invariant, discipline gap) during a session, the gate routes the codification to the cross-family-readable substrate spot per the pattern type table above.
- Default-to-harness-private is restricted to the narrow "harness-specific gotcha" case.
Migrate the 6 session-pattern memories to their shared-substrate homes:
- feedback_hooks_human_only_automation_bypasses.md → ADR amendment OR new ADR (substrate-architecture invariant)
- feedback_partial_lane_pr_close_target.md → .agents/skills/pull-request/references/partial-lane-close-target.md (skill-domain discipline)
- feedback_merge_gate_idle_recurrence.md → .agents/skills/post-review-pickup/references/merge-gate-self-survey.md (cross-cutting reflex)
- feedback_adr_worked_example_cascade_violation.md → ADR 0007 amendment OR new ADR
- feedback_agents_md_24kib_hard_cap.md → AGENTS_ATLAS section OR pull-request-workflow.md §1.1 enhancement
- feedback_worktree_git_attribution.md → .claude/CLAUDE.md in-repo (Claude-specific gotcha; KEEP harness-local but in REPO not user-home)
Update AGENTS.md §13 (Self-Evolving Systems / Continuous MX Rule-Refinement Loop) to explicitly name the Substrate-Pattern Codification Gate as the routing primitive.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Substrate-pattern codification routing	This ticket + operator-direction 2026-05-18	New discipline gate in `pull-request-workflow.md` OR new skill routes substrate-patterns to per-type substrate spots	Authors fall through to harness-private memory (default-to-private) which IS the current friction	Workflow doc / skill reference / ADR per pattern	Cross-family review verifies routing is followed; gate fires when pattern emerges
Existing 6 memories from session 2026-05-18	This ticket + operator-direction	Migrate to shared-substrate spots per the table	Leave as harness-private (current state — invisible to GPT/Gemini)	The migrated files themselves	`git log` shows the migration; cross-family A2A confirms peers can access

Acceptance Criteria

AC1: Substrate-Pattern Codification Gate defined in a shared-substrate location (workflow doc OR new skill); routing table per pattern type included.
AC2: The 6 session-pattern memories migrated to their shared-substrate homes (or explicitly retained as harness-private with substantive rationale).
AC3: AGENTS.md §13 (or equivalent) references the gate as the routing primitive for newly-discovered substrate patterns.
AC4: Cross-family review verifies the gate is mechanically followable (agent can route from "I learned X" → "X belongs in Y" deterministically).
AC5: Operator green-light on the gate shape before fanout to all 3 harnesses (this is substrate-architecture discipline; high-blast).

Out of Scope

Mechanically enforcing the gate at commit/PR time (lint/CI). The gate is discipline-only in v1; mechanical enforcement is a separate ticket if the discipline doesn't hold.
Migrating EVERY existing feedback_*.md across all agents' personal memory stores. Only the SESSION-2026-05-18 memories are operator-asked; broader migration is a follow-up if pursued.
Standardizing memory-file format across harnesses. The discipline is about LOCATION not FORMAT.

Avoided Traps

Forcing ALL substrate-patterns into shared substrate — rejected. Harness-specific gotchas (e.g., Claude Code's worktree git config inheritance behavior) ARE harness-private by definition; other harnesses don't have the same gotcha. Forcing these to shared substrate is bloat without value. The discipline must distinguish pattern types.
Authoring 6 separate migration PRs — rejected without operator green-light. Bundling vs splitting is operator-decision based on review-load preference.
Treating this as "improve memory storage" — rejected. The issue is ROUTING and CROSS-FAMILY VISIBILITY, not memory storage mechanics. Operator-direction was specifically about codification SPOT.

Operator direction: in-session 2026-05-18 ~20:40Z (Origin Session ID below; correction to my just-prior idle proposing feedback_merge_gate_idle_recurrence.md as the substrate-pattern memory)
AGENTS.md §13.1 / §13.2: Contributions Over Commits + Friction → Gold core values — the discipline this gate operationalizes
feedback_hooks_human_only_automation_bypasses.md (and 5 other session memories): the 6 candidates for migration per AC2
#11591 (operator-green-light-pending): adjacent terminology-restoration ticket — similar substrate-evolution shape

Operator Green-Light Required

This is high-blast substrate-architecture discipline. The gate shape should converge cross-family BEFORE fanout to AGENTS.md / skills / ADRs. Operator-decision on whether to:

(a) Pursue this as the substrate-pattern-codification-discipline ticket
(b) Defer to operator-authored substrate work in a different shape
(c) Drop entirely (acceptable if operator considers the harness-private default acceptable for some scope)

PR-author lane should NOT start until operator green-lights the gate shape.

Origin Session ID: 1b7a3403-06f3-4862-be80-479e129656de Retrieval Hint: query_raw_memories("substrate-pattern codification spot harness-private cross-family AGENTS_ATLAS skills references ADR migration session 2026-05-18")