Neo AI Architecture Masterplan (Antigravity & Agent SDK)

This document serves as the ground truth and context provider for all future autonomous sessions working on the Neo.mjs AI toolchain. It defines the grand vision, the infrastructural shifts, and the long-term execution sequence required to enable unconstrained AI independence on the Neo.mjs project.

1. The Grand Vision

The ultimate product is a framework capable of autonomous self-improvement. By running persistent background sessions on parallel hardware (e.g., a secondary Mac), Antigravity (the autonomous agent suite) must be able to independently traverse GitHub tickets, resolve issues, write blog posts, refine core infrastructure (SSR, SSG+, Virtual DOM), and chart the strategic future of the project without constant human direction.

To break the chicken-and-egg problem where the AI is limited by its lack of holistic codebase understanding and lack of long-term strategic intuition, we are building specialized subsystems to form an "AI Application Engine."

2. Core Concepts & Subsystems

A. REM / Dream Mode & The "Sandman" Agent

Currently, AI agents operate in "flat" sessions—once 5 previous sessions drop off the summary limit, critical strategic breakthroughs can be lost.

REM Mode is continuous asynchronous processing meant to mimic human subconscious problem solving.

• The Sandman agent runs during downtime. It will not write software code.
• Instead, it operates strictly on databases and markdown logs.
• It processes local issue trackers (synced via github-workflow), session summaries from the memory core, and prior architectural documents.
• It synthesizes competing priorities (business side vs. technical depths) into curated Markdown outputs, effectively highlighting the "Golden Path".

B. Hybrid GraphRAG & The Native Edge Graph

While our current semantic vector database (ChromaDB) successfully handles unstructured deep-dive semantic searches across memories and the knowledge base, it lacks relational topology.

The Pivot (Hybrid Architecture): We will keep ChromaDB for its high-performance semantic vector search, but augment it by building a native, zero-dependency Graph Database using the Neo.mjs class architecture. This creates a true GraphRAG ecosystem powering two distinct instances:

1. The Application Engine & AI SDK Knowledge Graph (Public Context):

   • Maps the entire Neo.mjs codebase, framework rules, test coverage, and documentation.
   • Allows agents to traverse architectural edges (e.g., Neo.grid.View → Neo.component.Base → vnode hooks).

2. The Sandman Memory Graph (Private Context):

   • Stores episodic memories, ideas, previous sessions, priority weights, and retrospective insights.
   • The primary playground for the Sandman agent to connect unlinked concepts (e.g., merging "Task A" and "Task G" into a prioritized "Golden Path").

C. Composable Agent Skills (The Anthropic Standard)

To efficiently expand agent capabilities, we will adopt the emerging industry standard for Agent Skills (as defined by Anthropic).

• Definition: Skills are standardized, modular instruction sets (using SKILL.md) that teach AI agents to handle repetitive workflows (e.g., file creation, data analysis, coding). They act as portable, reusable expertise.
• Standards: Industry standards (as of early 2026) dictate using SKILL.md for explicit instructions and JS/Python scripts for automation, fully integrated with MCP for external data access.
• Portability: These skills are portable across Claude Code, Cursor, and our own Antigravity Agent SDK. By adopting this standard, any sub-agent (Navigator, Librarian, Sandman) can stitch together these building blocks to execute complex workflows autonomously.

3. The Execution Roadmap & Epics

The sequence of execution is critical. It must be ordered purely on AI Enablement—every step must act as a force multiplier for the AI to execute the next step.

Phase 1: Workflow Enablement

1. Epic: Agent Skills Implementation: Implement the Anthropic SKILL.md standard. This is the ultimate foundational multiplier. By establishing standardized slash commands and workflows first, the AI can encode repetitive codebase parsing, UI debugging, and test validation into reusable skills, making all following phases exponentially faster.

Phase 2: Technical Awareness (GraphRAG)

2. Epic: Native Graph Database Engine: Build the zero-dependency JS Graph Database that sits alongside ChromaDB, providing the topological edge store.
3. Epic: Application Engine Knowledge Graph Mapping: This is the massive leap in technical capability. We parse the Neo.mjs hierarchy, hooks, and relationships into the Native Graph. Once completed, the AI gains "Senior Neo Engineer" intuition, enabling complex architectural capabilities (SSR, grids) and preventing hallucinations.

Phase 3: Strategic Consciousness (REM/Sandman)

4. Epic: The Sandman Prototype: With the Knowledge Graph completed, the Sandman agent wakes up. Instead of just naively summarizing text, the Sandman can now traverse the Application Engine Graph while parsing local issue tickets and session memories. It connects episodic thoughts to actual framework loci, enabling true subconscious "Dream" routing and prioritizing the Golden Path.

Phase 4: Expansion

5. Epic: Conversational UIs & Neural Link Extensions: Expand the real-time websocket bridge (Neural Link) to support next-generation UI testing and AI-driven UI interaction workflows.