---
id: 10068
title: '[docs] Formalize memory-first reflex as per-turn mandate for ticket work'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - tobiu
createdAt: '2026-04-18T19:57:03Z'
updatedAt: '2026-05-15T12:42:11Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10068'
author: tobiu
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-04-18T20:18:34Z'
---
# [docs] Formalize memory-first reflex as per-turn mandate for ticket work

## Problem

On 2026-04-18 I spent ~15 minutes re-deriving the root cause of #9837 (MCP output-schema strict-validation failures) 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) — plain-language: *"`additionalProperties: false` behavior per AJV JSONSchema enforcement"* — with a named prior local fix (added `engines` field to `memory-core/openapi.yaml`). I only found it after tobiu asked me to check afterwards.

The per-turn mandate for memory queries already exists abstractly at `AGENTS_STARTUP.md §3.3` (Two-Stage Query Protocol). The deep playbook already exists at `learn/agentos/StrategicWorkflows.md` (Regression Bug Analysis Workflow — three-dimensional git + ticket + memory pattern). They're just not cross-linked, and the abstract mandate doesn't enumerate concrete triggers.

## Why this matters

Agents — whether freshly initialised or seasoned — often reach for `git log`, `grep`, or node reproductions before they reach for the memory core, simply because those tools are top-of-mind. Memory Core's semantic search is the cheapest first move for "has this been thought through before?" across 8K+ memories and 794 session summaries: vector embeddings surface loosely-worded prior context that keyword grep misses entirely. The reflex to ask *"what would tobi do here?"* — or to browse related summaries before committing to a course — is what stops agents from reinventing the wheel on decisions that were already debated and resolved in prior sessions.

This is doubly important because memory content is **authored by many agents across many harnesses** (Claude Code, Antigravity/Gemini, others). A bug diagnosed by Gemini on Monday can save Claude on Friday — but only if the Friday agent queries first.

## Architectural Reality (Current Layer Map)

| Layer | File | What it does | Gap |
|---|---|---|---|
| Per-turn mandate | `AGENTS_STARTUP.md §3.3` | Two-Stage Query Protocol (abstract rule) | **No concrete triggers enumerated; no cross-link to StrategicWorkflows** |
| Deep playbook | `learn/agentos/StrategicWorkflows.md` | Full Regression Bug Analysis Workflow | **Not in mandatory startup reading list; not discoverable on boot** |
| Pre-work | `.agent/skills/ticket-intake/` §1.3 | Historical Amnesia Check for new tickets | Already correct — no change |
| Infrastructure | `.agent/skills/self-repair/` | Infrastructure triage when Agent OS itself is sick | **Out of scope** — regression forensics presupposes a healthy OS; putting memory-first inside self-repair would be circular when memory-core is the broken thing |

## Scope of Work (three surgical edits)

### 1. `AGENTS_STARTUP.md` Session Initialization (§2)
Add `learn/agentos/StrategicWorkflows.md` to the mandatory reading list — the existing Regression Workflow becomes discoverable on every session boot.

### 2. `AGENTS_STARTUP.md` Two-Stage Query Protocol (§3.3)
After the existing "Contextual Ledger" mandate, add explicit trigger enumeration:

> **Memory-query triggers (mandatory before git/grep/test work).** Run `query_raw_memories` + `query_summaries` on symptom keywords when you hit any of:
> - User reports a regression ("used to work", "suddenly broken", "worked before my change")
> - Surprise validation failures, schema mismatches, `additionalProperties` rejections
> - Architecturally non-obvious code where "why was it done this way" is unclear
> - Decision points where prior trade-offs likely inform the right answer
>
> Memory Core's semantic search routinely surfaces prior decisions keyword grep would miss — *"what would tobi do here?"*. Memories are authored across many agents and harnesses; a diagnosis captured in a prior session saves re-derivation in the current one. See [Regression Bug Analysis Workflow](learn/agentos/StrategicWorkflows.md) for the three-dimensional git + ticket + memory pattern.

### 3. `learn/agentos/StrategicWorkflows.md` Step 4
Currently shows CLI form `npm run ai:query-memory -- -q "..."`. Add MCP-tool form (`query_raw_memories`, `query_summaries`) which is what agents actually invoke inside MCP sessions. Small unification — same workflow, two invocation surfaces.

## Avoided Traps

- **Not** extending `.agent/skills/self-repair/`. Per user correction: self-repair's scope is infrastructure recovery; regression forensics presupposes a healthy Agent OS. Memory-first inside self-repair is circular if memory-core itself is the sick component.
- **Not** creating a new `.agent/skills/regression-analysis/` skill. Skill proliferation for an analytical pattern fragments the registry. The reflex is per-turn operational, not a discrete procedure — belongs in the operational mandate layer, not a skill.
- **Not** building tooling-level enforcement (auto-run memory queries on regression keywords). Valid future direction, but out of scope for a docs refinement. Worth a separate ticket if the docs fix proves insufficient.

## Acceptance Criteria

- [ ] `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)

## Timeline

- 2026-04-18T19:57:05Z @tobiu added the `documentation` label
- 2026-04-18T19:57:05Z @tobiu added the `enhancement` label
- 2026-04-18T19:57:06Z @tobiu added the `ai` label
- 2026-04-18T19:57:10Z @tobiu assigned to @tobiu
- 2026-04-18T19:58:56Z @tobiu referenced in commit `c7560cc` - "docs(agentos): formalize memory-first reflex as per-turn mandate for ticket work (#10068)"
- 2026-04-18T20:02:59Z @tobiu cross-referenced by PR #10069
- 2026-04-18T20:18:34Z @tobiu referenced in commit `816ae4c` - "docs(agentos): formalize memory-first reflex as per-turn mandate for ticket work (#10068) (#10069)"
- 2026-04-18T20:18:35Z @tobiu closed this issue
- 2026-04-18T20:42:46Z @tobiu cross-referenced by #10070
- 2026-04-18T20:50:31Z @tobiu cross-referenced by PR #10071

