agentopology 0.2.4 → 0.3.0

package/spec/grammar.md

@@ -207,6 +207,7 @@ perm-enum       = perm-identifier
 | `fan-out` | Parallel slices |
 | `event-driven` | Pub-sub |
 | `human-gate` | Human approval points |
+| `brain` | Agent-maintained, Obsidian-portable markdown knowledge graph |
 
 ---
 
@@ -360,6 +361,7 @@ scale-field     = 'mode' ':' ('auto' | 'fixed' | 'config')
 | `behavior` | `advisory` / `blocking` | no | `blocking` | Advisory never blocks flow |
 | `memory` | name-list | no | `[]` | Store IDs this agent can access (V35) |
 | `retrieval` | identifier | no | -- | Retrieval strategy ID for memory queries (V35) |
+| `custodian-of` | name-list `{ does: name-list }?` | no | -- | Store IDs this agent **maintains** (not just reads). The primitive behind the `brain` pattern. Optional `does:` declares maintenance verbs (e.g. `link, tag, index, dedupe`). Refs validated by V88. |
 | `skills` | name-list | no | `[]` | Skills to preload |
 | `mcp-servers` | name-list | no | `[]` | MCP servers available |
 | `background` | boolean | no | `false` | Run in background |
@@ -531,7 +533,7 @@ store-field     = 'type' ':' store-type
                 | lifecycle-block
                 | backend-config-block
 store-type      = 'semantic' | 'episodic' | 'procedural' | 'entity'
-                | 'graph' | 'user' | 'session' | 'temporal'
+                | 'graph' | 'user' | 'session' | 'temporal' | 'brain'
 scope-enum      = 'agent' | 'user' | 'session' | 'org' | 'global'
 isolation-enum  = 'strict' | 'soft' | 'none'
 backend-enum    = 'lancedb' | 'sqlite-vec' | 'chroma' | 'kuzu' | 'falkordb'
@@ -639,10 +641,12 @@ memory {
 | `description` | string | no | -- | Human-readable purpose |
 | `scope` | scope-enum | no | -- | Access scope (V32 warning if omitted) |
 | `isolation` | isolation-enum | no | -- | Isolation level between scopes |
-| `backend` | backend-enum | yes | -- | Storage backend (V30 enum check) |
+| `backend` | backend-enum | yes | -- | Storage backend (V30 enum check). For `type: brain`, defaults to `files` and is exempt from the enum check (V81). |
 | `path` | string | no | -- | File system path for local backends |
 | `connection` | secret-string | no | -- | Connection URI for remote backends (V34) |
 | `extraction` | extraction-enum | no | -- | Entity/fact extraction method |
+| `format` | string | no | -- | File format/convention for file-native stores. For `brain`, typically `obsidian` ([[wikilinks]], #tags, YAML frontmatter) — a promise the store round-trips as a real Obsidian vault. |
+| `sources` | sources-block | no | -- | **Presentation only** — provenance styling for the brain graph view. Maps a note's `source:` frontmatter to a color/icon. Visualizer-only; bindings ignore it. See below. |
 | `embedding` | embedding-block | no | -- | Embedding configuration (V31 warning if omitted for semantic/episodic/procedural) |
 | `index` | index-block | no | -- | Index/collection configuration |
 | `ingestion` | ingestion-block | no | -- | Data ingestion configuration |
@@ -654,6 +658,30 @@ memory {
 
 **`backend-config`:** A passthrough block for backend-specific key-value pairs not covered by the standard fields. Stored as `Record<string, unknown>` on the AST. Same pattern as `ProviderDef.extra`.
 
+**The `brain` store type (file-native).** A `brain` store is the file-native memory primitive behind the `brain` pattern: a folder of Obsidian-format markdown where the graph is a *projection* of the files, not a separate database. It is deliberately backend-less — its `backend` defaults to `files` and is exempt from the backend-enum check (V81), it needs no embedding (V82), and it compiles to direct file access (no MCP server). Edges come from inline `[[wikilinks]]` and `#tags`; backlinks are computed. Because the format is Obsidian, a `brain` store round-trips as a real Obsidian vault — agents build it, a human opens it in Obsidian for the graph view, and an existing vault becomes an agent-readable brain with zero migration. Heavyweight stores (`semantic`, `graph`, `entity`) remain available as an opt-in power-up alongside a brain. See `docs/company-brain-design.md`.
+
+**Custody (`custodian-of`).** Custody is the one new primitive the brain pattern needs. `memory:` grants an agent *read* access to a store; `custodian-of:` makes the agent *responsible for the store's upkeep* — wiring dropped files into the graph (resolving mentions into `[[wikilinks]]`, assigning `#tags`, updating index/hub notes, flagging ghost nodes and duplicates). The optional `does:` sub-list declares the maintenance verbs as visible architecture (like an optional type annotation); omitting it lets the agent infer its duties from its prompt. The verb *names* are language vocabulary; *how* each verb is performed well is an implementation/skill concern, not part of the spec. V88 validates that every `custodian-of` reference resolves to a declared store and warns when custody targets a non-brain store.
+
+**Provenance styling (`sources`).** A presentation-only sub-block on a brain store that colors the graph view by where each note came from. Each named entry maps a source key (matching a note's `source:` frontmatter, stamped by its ingester) to a `color` (hex) and/or `icon` (a file path):
+
+```
+store brain {
+  type: brain
+  path: "brain/"
+  sources {
+    gmail {
+      color: "#EA4335"
+      icon: "./logos/gmail.svg"
+    }
+    slack {
+      color: "#4A154B"
+    }
+  }
+}
+```
+
+This is **strictly cosmetic and affects only the `visualize-brain` rendering** — it never touches ingestion, agents, files, or binding output. Bindings emit nothing for it; delete it and the brain behaves identically (the graph just falls back to category coloring). The language stores **no image bytes** — only the path string; the visualizer reads the icon file at generate-time and inlines it as a `data:` URI, keeping the output a single self-contained HTML file. When a node's `source` matches a `sources` key, it is colored/iconed accordingly; otherwise it falls back to category-based coloring (person/org/topic inferred from tag namespaces).
+
 **Local vs remote backends:** Backends `lancedb`, `sqlite-vec`, `sqlite`, `kuzu`, and `chroma` are local-first (use `path`). Backends `pinecone`, `qdrant`, `pgvector`, `neo4j`, `mongodb`, and `falkordb` are remote (require `connection`, V34).
 
 ##### `embedding` sub-block
@@ -1482,6 +1510,8 @@ agent explorer {
 
 **Why extensions:** The core `.at` language defines universal constructs that work across all platforms. Extensions allow bindings to expose platform-specific features (e.g., Claude Code's `memory: project`, Codex's `sandbox: true`) without adding fields to the core spec that only one platform uses. This keeps the language clean while remaining fully extensible.
 
+**Seam marker for the hybrid:** `extensions { claude-workflow { execution: workflow } }` on an agent marks its phase for the embedded-workflow rung — the deterministic fan-out compiled by the `claude-workflow` binding while the rest of the topology compiles to the `claude-code` host. Unmarked topologies compile to pure `claude-code`, unchanged (the hybrid is opt-in). See `docs/AT_VS_WORKFLOW_STRATEGY.md`.
+
 **LL(2) note:** `extensions` is a block keyword. The parser sees `extensions` `{` and enters the extensions production. Inside, each `<identifier>` `{` starts a binding namespace block. No ambiguity -- `extensions` only appears inside other blocks, never at the top level.
 
 ---
@@ -1790,11 +1820,20 @@ Bindings map universal permissions to platform-specific modes:
 
 | Binding | Status | Target |
 |---------|--------|--------|
-| `claude-code` | Stable | Claude Code agent files, settings, MCP config |
+| `claude-code` | Stable | Claude Code agent files, settings, MCP config (the event-driven HOST layer) |
+| `claude-workflow` | Stable | Claude Workflow tool script (`<topology>.workflow.js`) for the deterministic fan-out rung, plus SEAM/README/LOSSY-REPORT companion files |
+| `codex` | Stable | Codex agent definitions and config |
+| `gemini-cli` | Stable | Gemini CLI agent definitions and config |
+| `copilot-cli` | Stable | GitHub Copilot CLI agent definitions and config |
+| `openclaw` | Stable | OpenClaw soul.md, skill files, channel/gateway/workspace config |
+| `kiro` | Stable | Kiro agent definitions and config |
+| `cursor` | Stable | Cursor rules and agent config |
 | `agent-sdk` | Planned | Anthropic Agent SDK tool definitions |
 | `e2b` | Planned | E2B sandbox configuration |
 | `openai-swarm` | Planned | OpenAI Swarm agent definitions |
 
+**The `claude-code` + `claude-workflow` hybrid.** A single `.at` topology can compile to BOTH targets. `claude-code` is the HOST — the event-driven layer that owns agents, hooks, the Blackboard, concurrent observability, and the human/gate/branching nodes. `claude-workflow` is the embedded DETERMINISTIC rung — the parallel fan-out phases. They couple through the Blackboard files (`memory.workspace`): the host launches the rung and observes its Blackboard writes via a `PostToolUse` hook, giving concurrent observability the Workflow runtime can't do internally. The seam is opt-in: a phase joins the rung only when its agents carry `extensions { claude-workflow { execution: workflow } }`. Topologies with no such marker compile to pure `claude-code` exactly as before (backward compatible). See `docs/AT_VS_WORKFLOW_STRATEGY.md` for the rationale and `docs/bindings/claude-workflow-mapping.md` for the full primitive mapping.
+
 See `docs/bindings.md` for details on creating new bindings.
 
 ---