agentopology 0.2.5 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 <h1 align="center">AgenTopology</h1>
 
 <p align="center">
-  <strong>The Terraform for AI agents.</strong><br/>
-  Define your agent team once. Deploy to any platform.
+  <strong>Harness as code.</strong> The Terraform for AI agents.<br/>
+  Define your agent team — and its memory — once. Deploy to any platform.
 </p>
 
 <p align="center">
@@ -364,6 +364,36 @@ mcp-servers {
 }
 ```
 
+</td>
+</tr>
+<tr>
+<td>
+
+**Company Brain** — agent-maintained, Obsidian-portable
+```
+store brain {
+  type: brain          # markdown, no DB
+  path: "brain/"
+  format: obsidian     # ports both ways
+}
+agent librarian {
+  custodian-of: [brain]  # owns its upkeep
+}
+```
+
+</td>
+<td>
+
+**Provenance styling** — color the graph by source
+```
+store brain {
+  sources {
+    gmail { color: "#EA4335" icon: "./gmail.svg" }
+    slack { color: "#4A154B" }
+  }
+}
+```
+
 </td>
 </tr>
 </table>
@@ -389,6 +419,39 @@ In Claude Code, this compiles to a **file-based protocol** — a shared transcri
 
 ---
 
+## Company Brain — Knowledge That Builds Itself
+
+A **brain** is a folder of linked markdown that agents maintain, not you. It's the [Obsidian](https://obsidian.md) graph model — notes connected by `[[wikilinks]]` and `#tags` — but **agent-maintained instead of hand-curated**.
+
+```
+store brain {
+  type: brain          # file-native: markdown, no database, no embeddings
+  path: "brain/"
+  format: obsidian     # ports both ways — open it in Obsidian, the graph just works
+}
+
+agent librarian {
+  custodian-of: [brain] {       # OWNS the brain's upkeep, not just read access
+    does: [link, tag, index, dedupe]
+  }
+}
+```
+
+- **Custodian agents** own a memory layer. Drop a note in, the librarian wires it into the graph — resolving `[[links]]`, assigning `#tags`, updating hub notes. Humans drop; agents wire.
+- **Ingester agents** feed it from anywhere. One agent per source (Gmail, Slack, calendar) writes raw notes; the librarian links them. See [`examples/company-brain-team.at`](examples/company-brain-team.at).
+- **Pure markdown, zero infrastructure.** No vector DB, no MCP server. Coding agents retrieve with `grep`. The whole brain is a folder you can `git clone`.
+- **100% Obsidian-compatible.** The vault *is* an Obsidian vault — agents build it, you open it in Obsidian for the graph view. Or use our built-in graph viewer (below) and skip Obsidian entirely.
+
+**See it without Obsidian** — render any brain vault as an interactive graph in a single self-contained HTML file:
+
+```bash
+agentopology visualize-brain brain/
+```
+
+Nodes are colored by what they *are* (person / org / topic) and by where they *came from* (declare `sources { gmail { color, icon } }` and notes from Gmail render in Gmail red with the logo). When you `visualize` a topology that owns brains, the two graphs **cross-link** — jump from the team diagram to its brain and back.
+
+This is **brain as code**: you declare the brain's architecture — its layers, its custodians, its sources — the same way you declare the agent team. See [`docs/company-brain.md`](docs/company-brain.md) for the full walkthrough.
+
 ---
 
 ## Programmatic API
@@ -462,6 +525,8 @@ You can `agentopology visualize` it into an interactive graph. You can hand it t
 - [`data-processing.at`](examples/data-processing.at) — ETL pipeline with batch processing and metering
 - [`scheduled-monitor.at`](examples/scheduled-monitor.at) — Monitoring system with scheduled health checks
 - [`openclaw-assistant.at`](examples/openclaw-assistant.at) — Customer support with routing and scheduling
+- [`company-brain.at`](examples/company-brain.at) — A plug-and-play company brain (librarian + researcher)
+- [`company-brain-team.at`](examples/company-brain-team.at) — A team that ingests (Gmail/Slack/calendar), wires, and audits a brain
 
 ---
 
@@ -472,7 +537,8 @@ agentopology validate <file>              Validate an .at file (82 rules)
 agentopology scaffold <file> --target <t> Generate platform configs
 agentopology sync <file> --target <t> --dir <d>  Sync platform files back to .at
 agentopology import --target <t> --dir <d>       Reverse-engineer platform files to .at
-agentopology visualize <file>             Interactive topology graph
+agentopology visualize <file>             Interactive topology graph (+ cross-links any brains)
+agentopology visualize-brain <folder>     Render a brain vault as an Obsidian-style graph (no Obsidian)
 agentopology export <file> --format <fmt> Export as markdown, mermaid, or json
 agentopology info <file>                  Topology analysis and suggestions
 agentopology targets                      List supported platforms

package/dist/bindings/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AA0xF/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAu4F/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -132,6 +132,58 @@ function gitkeep(dirPath) {
 function agentPhase(agent) {
     return agent.phase ?? Number.MAX_SAFE_INTEGER;
 }
+/**
+ * The standard meaning of each custody maintenance verb. The verb NAMES are
+ * language vocabulary (public); these one-line charters tell the agent what each
+ * verb means operationally. The deeper "how to do it brilliantly" stays in the
+ * skill repo (MOAT) — these are intentionally the safe, obvious definitions.
+ */
+const CUSTODY_VERBS = {
+    link: "find mentions of existing notes and turn them into `[[wikilinks]]` (add-only — never delete a human's links)",
+    tag: "assign `#nested/tags` consistent with the tag hierarchy already present in the vault",
+    index: "update the relevant hub note (a Map-of-Content that `[[links]]` the cluster) so the new note is reachable",
+    backlink: "rely on computed backlinks from the `[[links]]` you write — never author backlinks by hand",
+    dedupe: "flag near-duplicate notes for human review — never auto-merge or delete",
+    summarize: "keep a short synthesized summary at the top of hub notes, refreshed when the cluster changes",
+    heal: "repair broken links after renames and surface ghost nodes (`[[links]]` to notes that don't exist yet)",
+};
+/**
+ * Generate the custody charter section for an agent that is `custodian-of` one
+ * or more stores. This is what makes custody a real binding behavior: the agent
+ * gets a standing instruction set to MAINTAIN the store(s), not just read them.
+ */
+function generateCustodyCharter(agent, storeMap) {
+    const out = [];
+    out.push("## Custody — you maintain these stores");
+    out.push("");
+    out.push("You are the **custodian** of the store(s) below: you own their upkeep, not just read access. " +
+        "Humans drop raw notes; your job is to wire them into the graph and keep it healthy.");
+    out.push("");
+    for (const storeId of agent.custodianOf ?? []) {
+        const store = storeMap.get(storeId);
+        out.push(`### ${storeId}`);
+        if (store?.path) {
+            out.push(`The vault lives at \`${store.path}\`. Maintain it with \`Read\`, \`Write\`, \`Edit\`, \`Grep\`, \`Glob\` — no database, just files.`);
+        }
+        if (store?.format === "obsidian") {
+            out.push("It is **Obsidian-format** markdown: only ever write `[[wikilinks]]`, `#tags`, `![[embeds]]`, and YAML frontmatter — nothing custom — so the vault round-trips in Obsidian.");
+        }
+        out.push("");
+        // Maintenance verbs — declared ones, or the safe default set.
+        const verbs = (agent.custodianDoes && agent.custodianDoes.length > 0)
+            ? agent.custodianDoes
+            : ["link", "tag", "index", "heal", "dedupe"];
+        out.push("When a note is added or changed, perform these maintenance steps:");
+        for (const verb of verbs) {
+            const meaning = CUSTODY_VERBS[verb] ?? `apply the \`${verb}\` maintenance step`;
+            out.push(`- **${verb}** — ${meaning}`);
+        }
+        out.push("");
+        out.push("Wire add-only and conservatively: prefer leaving a human's content untouched over a risky rewrite. When unsure, flag for review rather than edit.");
+        out.push("");
+    }
+    return out;
+}
 /**
  * The set of phases that compile into the embedded workflow rung — every phase
  * that contains ≥1 agent marked `execution: workflow`. (Matches the
@@ -522,6 +574,13 @@ function generateAgents(ast) {
                 sections.push("");
             }
         }
+        // Custody — the agent OWNS the upkeep of these stores (the `brain` pattern).
+        // Generated even when the agent has no hand-written prompt, so custody is a
+        // real binding behavior, not just prose the author happened to write.
+        if (agent.custodianOf && agent.custodianOf.length > 0) {
+            const storeMap = new Map((ast.stores ?? []).map(s => [s.id, s]));
+            sections.push(...generateCustodyCharter(agent, storeMap));
+        }
         // Retrieval strategy — rich details
         if (agent.retrieval) {
             const retrieval = (ast.retrievals ?? []).find(r => r.id === agent.retrieval);
@@ -1428,13 +1487,52 @@ function generateMemory(ast) {
     if (memory.workspace) {
         files.push(gitkeep(`.claude/skills/${name}/runs`));
     }
-    // Store directory markers
+    // Store directory markers. A `brain` store is a real, user-facing Obsidian
+    // vault — it lives at its declared `path:` (e.g. `brain/`), not buried under
+    // `.claude/stores/`, so a human can open the folder directly in Obsidian.
+    // We seed it with a root Map-of-Content note so the vault opens to something.
     const stores = ast.stores ?? [];
     for (const store of stores) {
-        files.push(gitkeep(`.claude/stores/${store.id}`));
+        if (store.type === "brain") {
+            const vault = (store.path ?? `${store.id}/`).replace(/\/+$/, "");
+            files.push(brainVaultSeed(store, vault));
+        }
+        else {
+            files.push(gitkeep(`.claude/stores/${store.id}`));
+        }
     }
     return files;
 }
+/**
+ * Seed a brain vault with a root index note (`_brain.md`) — an Obsidian Map-of-
+ * Content the librarian grows over time. Gives the vault a home page and proves
+ * the format contract (wikilinks, tags, frontmatter) from the first commit.
+ */
+function brainVaultSeed(store, vault) {
+    const lines = [
+        "---",
+        "tags:",
+        "  - brain/index",
+        "---",
+        "",
+        `# ${toTitle(store.id)}`,
+        "",
+        store.description ? `> ${store.description}` : "> The company brain.",
+        "",
+        "This is the root index of the brain — a Map of Content the librarian maintains.",
+        "Drop new notes into this folder and run `/wire-in <file>` to fold them in.",
+        "",
+        "## Clusters",
+        "",
+        "_New hub notes appear here as the brain grows._",
+        "",
+    ];
+    return {
+        path: `${vault}/_brain.md`,
+        content: lines.join("\n"),
+        category: "machine",
+    };
+}
 /**
  * Generate memory command files for each store.
  *