agentopology 0.2.5 → 0.3.0

package/examples/company-brain-team.at

@@ -0,0 +1,241 @@
+# company-brain-team.at — A team of agents that build & maintain a company brain
+#
+# The flagship "company brain" topology. A folder of Obsidian-format markdown,
+# fed and maintained by a TEAM — not one librarian:
+#
+#   📧 gmail-ingester    ─┐
+#   💬 slack-ingester    ─┼─► drop raw notes into brain/    ─► 👤 librarian wires them
+#   📅 calendar-ingester ─┘    (each owns ONE source)          (links, tags, hubs)
+#                                                              ─► 🔍 auditor heals the graph
+#
+# - Ingesters are scheduled — they pull from their source and write raw markdown.
+# - The librarian is custodian-of the brain: it wires dropped notes into the graph.
+# - The auditor is custodian-of the brain too: it heals broken links, surfaces
+#   ghost nodes, and flags duplicates.
+# - A researcher reads the brain to answer questions.
+#
+# This is the whitespace: declarative + multi-agent team + Obsidian-portable +
+# agents own memory layers. Demonstrates `brain` + `custodian-of` + ingestion.
+
+topology company-brain-team : [brain, event-driven, human-gate] {
+
+  meta {
+    version: "0.1.0"
+    description: "A team of agents that ingest, wire, and maintain a company brain"
+  }
+
+  # --- The brain: one Obsidian-format markdown vault, no database ---
+
+  memory {
+    store brain {
+      type: brain
+      description: "The company brain — fed by ingesters, wired by the librarian"
+      path: "brain/"
+      format: obsidian
+      scope: org
+
+      # Presentation only — colors/icons for the graph view, by provenance.
+      # A note's `source:` frontmatter (stamped by its ingester) maps to a look.
+      # Cosmetic: bindings ignore this; delete it and the brain works the same.
+      sources {
+        gmail {
+          color: "#EA4335"
+          icon: "./logos/gmail.svg"
+        }
+        slack {
+          color: "#4A154B"
+          icon: "./logos/slack.svg"
+        }
+        calendar {
+          color: "#4285F4"
+        }
+      }
+    }
+  }
+
+  # --- Ingesters: each owns ONE external source, writes raw notes ---
+
+  agent gmail-ingester {
+    model: sonnet
+    description: "Pulls notable emails and writes them as raw notes into the brain"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [gmail]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest email into the brain. On each run:
+        - Pull recent notable threads (decisions, deals, intros, commitments).
+        - For each, write ONE raw markdown note into `brain/` with a clear title
+          and YAML frontmatter (date, source: gmail, participants).
+        - Do NOT wire links or tags — that is the librarian's job. Just capture
+          the content faithfully. Skip noise (newsletters, automated mail).
+    }
+  }
+
+  agent slack-ingester {
+    model: sonnet
+    description: "Captures key Slack decisions and threads as raw notes"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [slack]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest Slack into the brain. On each run, capture threads where a
+        decision was made, a commitment given, or knowledge shared. Write each
+        as ONE raw markdown note in `brain/` with frontmatter (date, source:
+        slack, channel). Leave linking and tagging to the librarian.
+    }
+  }
+
+  agent calendar-ingester {
+    model: sonnet
+    description: "Turns meetings into raw notes (attendees, outcomes)"
+    tools: [Read, Write, Grep, Glob]
+    mcp-servers: [calendar]
+    writes: ["brain/"]
+
+    prompt {
+        You ingest calendar events into the brain. For meetings that mattered,
+        write ONE raw markdown note in `brain/` with frontmatter (date, source:
+        calendar, attendees) and any outcomes/notes you can infer. No linking —
+        that is the librarian's job.
+    }
+  }
+
+  # --- Librarian: custodian that WIRES dropped notes into the graph ---
+
+  agent librarian {
+    model: sonnet
+    description: "Wires raw notes into the brain graph — links, tags, hubs"
+    tools: [Read, Write, Edit, Grep, Glob]
+
+    custodian-of: [brain] {
+      does: [link, tag, index, dedupe]
+    }
+
+    prompt {
+        You are the brain's librarian. Raw notes arrive from the ingesters and
+        from humans. You never invent content — you wire what is dropped in.
+        Resolve mentions into [[wikilinks]], assign #nested/tags, keep the hub
+        notes current, and flag duplicates. Leave ghost links to mark gaps.
+    }
+  }
+
+  # --- Auditor: custodian that keeps the whole graph HEALTHY ---
+
+  agent auditor {
+    model: opus
+    description: "Heals the brain — broken links, ghost nodes, orphans, dupes"
+    tools: [Read, Edit, Grep, Glob]
+
+    custodian-of: [brain] {
+      does: [heal, dedupe, index]
+    }
+
+    prompt {
+        You audit the brain's health. Find and repair broken [[links]] after
+        renames, surface ghost nodes (links to notes that don't exist), flag
+        orphan notes (nothing links to them), and propose merges for duplicates.
+        Conservative: repair links and report issues — never delete a human's note.
+    }
+  }
+
+  # --- Researcher: READS the brain to answer questions ---
+
+  agent researcher {
+    model: sonnet
+    description: "Answers questions by traversing the brain"
+    tools: [Read, Grep, Glob]
+    memory: [brain]
+
+    prompt {
+        Answer questions using only the brain in `brain/`. Grep for relevant
+        notes, follow their [[wikilinks]] and #tags, and cite notes by filename.
+    }
+  }
+
+  # --- Actions (flow entry/exit points) ---
+
+  action wire-in {
+    kind: inline
+    description: "Fold a dropped or freshly-ingested note into the brain"
+  }
+
+  action audit {
+    kind: report
+    description: "Report the brain's health: ghosts, orphans, broken links, dupes"
+  }
+
+  action query {
+    kind: inline
+    description: "Ask the brain a question"
+  }
+
+  # --- Flow: ingesters feed the librarian; auditor runs after; researcher reads ---
+
+  flow {
+    gmail-ingester    -> wire-in
+    slack-ingester    -> wire-in
+    calendar-ingester -> wire-in
+    wire-in           -> librarian
+    librarian         -> auditor
+    auditor           -> audit
+    query             -> researcher
+  }
+
+  # --- Schedule: ingesters and the auditor run on their own cadence ---
+
+  schedule {
+    job pull-email {
+      cron: "0 */2 * * *"
+      agent: gmail-ingester
+    }
+    job pull-slack {
+      cron: "0 */2 * * *"
+      agent: slack-ingester
+    }
+    job pull-calendar {
+      cron: "0 8 * * *"
+      agent: calendar-ingester
+    }
+    job nightly-audit {
+      cron: "0 3 * * *"
+      agent: auditor
+    }
+  }
+
+  # --- Triggers: humans can wire a file or ask the brain anytime ---
+
+  triggers {
+    command wire-in {
+      pattern: "/wire-in <FILE>"
+      argument: FILE
+      description: "Fold a dropped markdown file into the brain"
+    }
+    command query {
+      pattern: "/ask <QUESTION>"
+      argument: QUESTION
+      description: "Ask the brain a question"
+    }
+  }
+
+  # --- External sources the ingesters connect to ---
+
+  mcp-servers {
+    gmail {
+      type: stdio
+      command: "npx"
+      args: ["-y", "gmail-mcp-server"]
+    }
+    slack {
+      type: stdio
+      command: "npx"
+      args: ["-y", "slack-mcp-server"]
+    }
+    calendar {
+      type: stdio
+      command: "npx"
+      args: ["-y", "calendar-mcp-server"]
+    }
+  }
+}

package/examples/company-brain.at

@@ -0,0 +1,104 @@
+# company-brain.at — A plug-and-play company brain
+#
+# A folder of Obsidian-format markdown, maintained by agents, not by hand.
+# - Humans drop a new note and run /wire-in. The librarian links & tags it.
+# - The researcher traverses the [[link]] graph (with grep) to answer questions.
+# - No vector DB, no MCP server. The brain is a folder you can git clone and
+#   open in Obsidian for the graph view.
+#
+# Demonstrates the `brain` PATTERN + the `custodian-of` PRIMITIVE.
+
+topology company-brain : [brain, human-gate] {
+
+  meta {
+    version: "0.1.0"
+    description: "An agent-maintained, Obsidian-portable company brain"
+  }
+
+  # --- The brain itself: one markdown store, no backend ---
+
+  memory {
+    store brain {
+      type: brain                 # NEW store type — no DB, just files
+      description: "The company brain — a folder of linked markdown"
+      path: "brain/"              # this folder IS a valid Obsidian vault
+      format: obsidian            # [[wikilinks]], #nested/tags, YAML frontmatter
+      scope: org
+    }
+  }
+
+  # --- The librarian: KEEPER of the brain (the new primitive) ---
+
+  agent librarian {
+    model: sonnet
+    description: "Maintains the brain — wires new notes into the graph"
+    tools: [Read, Write, Edit, Grep, Glob]
+
+    custodian-of: [brain] {       # owns upkeep, not just read access
+      does: [link, tag, index, dedupe]   # OPTIONAL verbs — visible strategy
+    }
+
+    prompt {
+        You are the brain's librarian. The brain lives in `brain/` as Obsidian
+        markdown. You never invent content — you wire what's dropped in.
+
+        When a note is added or changed:
+        - link:   find mentions of existing notes and turn them into [[wikilinks]]
+        - tag:    add #nested/tags consistent with the existing tag hierarchy
+        - index:  update the relevant hub note (a Map-of-Content that [[links]]
+                  the cluster) so the new note is reachable
+        - dedupe: flag near-duplicate notes for human review; never auto-delete
+
+        Backlinks are computed from the [[links]] you write — never author them
+        by hand. If a note links to something that doesn't exist yet, leave the
+        ghost link; it marks a gap to fill later.
+    }
+  }
+
+  # --- The researcher: READS the brain to answer questions ---
+
+  agent researcher {
+    model: sonnet
+    description: "Answers questions by traversing the brain"
+    tools: [Read, Grep, Glob]
+    memory: [brain]               # read access — the ordinary wiring
+
+    prompt {
+        Answer questions using only the brain in `brain/`. Start by grepping for
+        relevant notes, then follow their [[wikilinks]] and #tags to gather the
+        full picture. Cite the notes you used by filename.
+    }
+  }
+
+  # --- What the human can do (actions are the flow entry points) ---
+
+  action wire-in {
+    kind: inline
+    description: "Fold a dropped markdown file into the brain"
+  }
+
+  action query {
+    kind: inline
+    description: "Ask the brain a question"
+  }
+
+  triggers {
+    command wire-in {
+      pattern: "/wire-in <FILE>"
+      argument: FILE
+      description: "Fold a dropped markdown file into the brain"
+    }
+    command query {
+      pattern: "/ask <QUESTION>"
+      argument: QUESTION
+      description: "Ask the brain a question"
+    }
+  }
+
+  # --- Flow ---
+
+  flow {
+    wire-in -> librarian          # human drops a file → librarian wires it
+    query   -> researcher         # human asks → researcher traverses & answers
+  }
+}

package/examples/logos/gmail.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><path fill="#fff" d="M6 12h36v26H6z"/><path fill="#EA4335" d="M6 14v3l18 12L42 17v-3l-18 12z"/><path fill="#FBBC04" d="M6 14v22h6V18l12 8 12-8v18h6V14l-18 12z" opacity=".9"/><path fill="#34A853" d="M6 36h6V18l-6-4z"/><path fill="#4285F4" d="M42 36h-6V18l6-4z"/><path fill="#C5221F" d="M6 14l18 12L42 14v-2H6z"/></svg>

package/examples/logos/slack.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48"><path fill="#36C5F0" d="M18 6a4 4 0 100 8h4V10a4 4 0 00-4-4z"/><path fill="#2EB67D" d="M42 18a4 4 0 10-8 0v4h4a4 4 0 004-4z"/><path fill="#ECB22E" d="M30 42a4 4 0 100-8h-4v4a4 4 0 004 4z"/><path fill="#E01E5A" d="M6 30a4 4 0 108 0v-4h-4a4 4 0 00-4 4z"/><path fill="#36C5F0" d="M18 18h8v8h-8z" opacity=".7"/></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentopology",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "The declarative language for multi-agent systems. Write once, scaffold for any platform.",
   "author": "Nadav Naveh",
   "license": "Apache-2.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