LearnNewsExamplesServices
Frontmatter
title>-
authortobiu
stateMerged
createdAtApr 18, 2026, 10:02 PM
updatedAtApr 18, 2026, 10:18 PM
closedAtApr 18, 2026, 10:18 PM
mergedAtApr 18, 2026, 10:18 PM
branchesdev ← agent/10068-memory-first-reflex
urlhttps://github.com/neomjs/neo/pull/10069
Merged
tobiu
tobiu commented on Apr 18, 2026, 10:02 PM

Summary

Three surgical documentation edits that promote the memory-first reflex from abstract mandate to concrete, trigger-driven behaviour — so agents reach for the Memory Core before git log, grep, or node reproductions, not after.

Scope

1. AGENTS_STARTUP.md §Step 1 — mandatory reading

Added learn/agentos/StrategicWorkflows.md as a Step 1 sub-paragraph. Existing agents already read Step 1's Codebase Overview and Documentation Taxonomy; this unlocks the Regression Bug Analysis Workflow (three-dimensional git + ticket + memory pattern) on every session boot without renumbering downstream steps.

2. AGENTS_STARTUP.md §3.3 — memory-query triggers

Between the existing Action and Contextual Ledger sections, inserted an explicit trigger enumeration:

  • User regression reports ("used to work", "suddenly broken")
  • Surprise validation failures / additionalProperties rejections / contract-breakdown symptoms
  • Architecturally non-obvious code ("why was it done this way")
  • Decision points where prior trade-offs likely matter

Plus a framing paragraph on why semantic search excels here: cross-agent cross-harness memory pool (Claude Code + Antigravity/Gemini + others), and vector embeddings surfacing loosely-worded context keyword grep would miss. Cross-linked to the Regression Workflow guide.

3. learn/agentos/StrategicWorkflows.md Step 4 — invocation parity

Guide previously showed only the npm run ai:query-memory CLI form. Added the MCP-tool form (query_summaries, query_raw_memories) that agents actually invoke inside MCP sessions. Same workflow, two invocation surfaces — correct one selected by context (active MCP session vs shell/CI).

Direct Motivation

During the execution of PR #10067 (#9837 — MCP output-schema drift), I spent ~15 minutes re-deriving the root cause via git diff + node reproductions. The exact diagnosis was already recorded in session ee4bd866-b00d-49e6-9c2f-860d51db521a (2026-04-16, the session that executed #10043) with plain-language wording: "additionalProperties: false behavior per AJV JSONSchema enforcement" and a named prior local fix. I only found it after tobiu asked me to check afterwards.

The per-turn mandate already existed abstractly; the deep playbook already existed in learn/agentos/. They just weren't cross-linked and the triggers weren't enumerated. This PR closes the discoverability loop.

Architectural Reality (why edits landed in these three files only)

Layer File Change
Per-turn mandate AGENTS_STARTUP.md §3.3 Added concrete triggers to the existing Two-Stage Query Protocol
Mandatory boot reading AGENTS_STARTUP.md §Step 1 Added StrategicWorkflows.md
Deep playbook learn/agentos/StrategicWorkflows.md Added MCP-tool form alongside CLI form
Pre-work .agent/skills/ticket-intake/ Unchanged — already covers pre-work memory queries correctly
Infrastructure .agent/skills/self-repair/ Unchanged — its scope is Agent OS recovery; regression forensics presupposes a healthy OS, so memory-first inside self-repair would be circular when memory-core is the sick component

Avoided Traps

  • Not extending .agent/skills/self-repair/. Per tobiu's correction: self-repair's scope is infrastructure recovery; putting memory-first there is circular if memory-core itself is down.
  • Not creating a new .agent/skills/regression-analysis/ skill. The reflex is per-turn operational, not a discrete procedure — belongs in the operational mandate layer, not a skill, to avoid registry fragmentation.
  • Not renumbering AGENTS_STARTUP steps. Step 2+ are referenced elsewhere in the document and in session-init memories; changing numbering would create dangling references. The new Strategic Workflows paragraph extends Step 1 alongside the existing Documentation Taxonomy paragraph.
  • Not building tooling-level enforcement (auto-run memory queries on regression keywords). Valid future direction but out of scope for a docs refinement.

Verification

No automated tests cover prose docs changes. Manual verification:

  • AGENTS_STARTUP.md parses as valid markdown (headers intact, no broken references)
  • StrategicWorkflows.md Step 4 continues to flow into Step 5
  • All Step numbers in AGENTS_STARTUP.md remain stable (verified via grep -n "^### Step")

Acceptance Criteria (from #10068)

  • AGENTS_STARTUP.md §2 lists learn/agentos/StrategicWorkflows.md as mandatory reading
  • AGENTS_STARTUP.md §3.3 contains the explicit trigger enumeration with universal framing
  • learn/agentos/StrategicWorkflows.md Step 4 shows MCP-tool form alongside CLI form
  • No changes to self-repair, ticket-intake, or other skills
  • No new skill created

Origin Session ID

7258d884-6c5d-40d5-b180-d58ae9a9d729 (this session; PR #10067 execution where the 15-minute re-derivation surfaced the gap)

Resolves #10068

tobiu
tobiu commented on Apr 18, 2026, 10:10 PM

Input from Claude Opus 4.7 (Claude Code):

❋ # PR Review Summary

Status: Comment (Self-Review)

Self-Review Opening: Self-review of #10068. I chose to land this purely as a docs edit at the operational-mandate layer rather than as a new skill or as a self-repair extension — the memory-first reflex is a per-turn reflex, not a procedure, and belongs where agents already read on every boot. Notable meta-irony called out below: this PR formalizes a reflex that I failed to apply in the session that surfaced the need for it. The change is retroactive self-correction.

Tech Debt Radar: deliberately not invoked. Rationale: docs(agentos) scope, +22/-2 LOC, no architectural shift. Borderline case because it affects every future session's boot-time context — but the change is additive to an existing mandate, not a new protocol. Calling it out for transparency.

📊 Evaluation Metrics

  • [ARCH_ALIGNMENT]: 88 — Correct layering. Per-turn mandate lands in AGENTS_STARTUP.md §3.3 (existing operational layer). Deep playbook stays in learn/agentos/. Skills left untouched per tobiu's correction. The four-trigger enumeration is concrete enough to fire on recognizable symptoms without being exhaustive to the point of unmemorability.
  • [CONTENT_COMPLETENESS]: 95 — Trigger examples reference the exact symptom class that caused the 15-min re-derivation (additionalProperties rejections). Framing paragraph names the real value (cross-harness memory pool, semantic search over 8K+ memories) rather than abstract platitudes. The "what would tobi do here?" phrasing is in the diff because tobiu explicitly named it — attribution preserved.
  • [EXECUTION_QUALITY]: 85 — Clean diffs, Step numbering preserved (verified grep -n "^### Step"), no broken references. Deduction: no automated verification possible for prose docs. Success is inherently qualitative (future session behavior), not testable in CI.
  • [PRODUCTIVITY]: 100 — Full workflow: dedup sweep → ticket #10068 → assign @me upfront → branch → three edits incorporating tobiu's two corrections (drop autonomous/supervised split, skip self-repair extension) → PR.
  • [IMPACT]: 75 — High ceiling (affects every future session boot across all harnesses), but relies on agent compliance. Docs-only, no enforcement mechanism. Real impact depends on whether future agents read + apply — the only way to measure is observing re-derivation frequency across upcoming sessions.
  • [COMPLEXITY]: 20 — The diff is trivial. The design thought was non-trivial (three rounds of user correction: where it fits, whether to split audiences, how to surface it). Final form is minimal because the correctsions prevented over-engineering.
  • [EFFORT_PROFILE]: Quick Win — high leverage (every future session), very small code surface.

🕸️ Context & Graph Linking

  • Target Epic / Issue ID: Resolves #10068
  • Related Graph Nodes: Born from post-hoc reflection on #10067 / #9837 (where the 15-min re-derivation happened). Conceptually sibling to .agent/skills/ticket-intake/ §1.3 Historical Amnesia Check (pre-work memory query) and AGENTS.md §4 Memory Core Protocol (Consolidate-Then-Save write path). Those cover writing memory and pre-work querying; this PR covers mid-work querying on symptom.
  • Origin Session ID: 7258d884-6c5d-40d5-b180-d58ae9a9d729

🧠 Graph Ingestion Notes

  • [KB_GAP]: learn/agentos/StrategicWorkflows.md is now mandatory reading but currently documents only ONE workflow (Regression Bug Analysis). This PR implicitly promotes it to an expansion point — future multi-step agent workflows (e.g., cross-harness handoff patterns, schema-drift audits, architectural-pivot protocols) belong here as sibling entries to the existing Regression Workflow. Worth noting so future agents treat it as an extensible cookbook, not a fossilized one-workflow doc.
  • [TOOLING_GAP]: No metric exists for whether agents actually apply the memory-first reflex after this change lands. Transcript analysis post-session (looking for sequences where git log/grep precedes query_raw_memories/query_summaries on regression-flavored prompts) would give an objective signal. Separate ticket worthy if post-merge observation suggests the docs fix is insufficient.
  • [RETROSPECTIVE]: This PR is itself an application of the existing AGENTS_STARTUP.md §3.3 "Mandate for Meta-Level Enhancements" — noticing recurrent friction during execution (my own re-derivation pattern), then proposing a meta-level fix rather than just solving the local problem. Worth remembering as a template: when an agent notices itself re-deriving something that should have been recallable, the fix is often a docs/workflow change rather than a code change. The validation of this PR isn't green tests — it's the absence of similar re-derivation moments in upcoming sessions. Self-correcting systems are measured by decay of their own failure modes, not by per-PR success criteria.

📋 Required Actions

  • Human QA (qualitative): observe next ~3-5 sessions for evidence the memory-first reflex is firing on regression symptoms. If agents still jump straight to git forensics, the docs fix needs a follow-up (hook-based enforcement per [TOOLING_GAP] above).
  • (Optional follow-up) File the metric/telemetry ticket from [TOOLING_GAP] if observation suggests docs alone are insufficient.
  • (Optional follow-up) Extend learn/agentos/StrategicWorkflows.md with additional cookbook workflows as they crystallize — keep it live, not fossilized.

No block-level changes to the content itself. The final state is tight.

Handoff: awaiting human merge per pull-request-workflow.md §5 (Human-in-the-Loop). I will not self-merge.