--- name: shared-brain-vault description: "Build and maintain a Git-synced Obsidian vault as shared working memory between user and AI agents. Use when: (1) Writing session summaries or project updates, (2) Recording decisions or learnings, (3) Adding people/profiles to the vault, (4) Populating or restructuring the vault, (5) Setting up multi-agent vault access, (6) Answering 'what did we decide' or 'where do we stand on X'. Triggers: 'shared brain', 'm3ta-brain', 'session summary', 'vault update', 'decision note', 'project status', 'what did we decide'." compatibility: opencode --- # Shared Brain Vault Manage the Git-synced Obsidian vault that serves as shared working memory between Sascha and his AI agents. ## Vault Location - **Repo**: `ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-brain.git` - **Standard clone path**: `~/m3ta-brain` (on m3-hermes this resolves to `/var/lib/hermes/m3ta-brain`) - **Local clone** (Sascha's machines): opened as Obsidian vault ## Scheduled Dream Pass / Cron When configuring or troubleshooting the nightly m3ta-brain Dream Pass cron, use this installed skill name: `shared-brain-vault`. Do **not** attach a non-existent `m3ta-brain` skill unless it has actually been deployed in the active Hermes profile. The cron prompt should explicitly say to load `shared-brain-vault` and then follow the canonical vault files `~/m3ta-brain/AGENTS.md` and `~/m3ta-brain/SCHEMA.md`; if those disagree with the skill, the vault files win. Pitfall: a cron run may do useful work and even commit/push, but still be marked `error` if the scheduled job references a missing skill. Fix the job's `skills` field first, then remember that `last_status` will remain `error` until the next successful run. Cross-agent note: the skill being installed in `~/.hermes/skills/` does not mean it exists in the AGENTS/agent-hub repo. If Sascha asks whether it is in the AGENTS repo, check/ensure `.agents/skills/shared-brain-vault/SKILL.md` separately. ## Read Order (Session Start) 1. `AGENTS.md` — the rules (canonical source for all agents) 2. `SCHEMA.md` — frontmatter types, tag taxonomy, naming conventions 3. `INDEX.md` — dashboard, what's new, what needs attention 4. `20-Projects/` — scan for current project context 5. `10-Preferences/do-dont.md` — hard rules Do NOT read the entire vault. Read by need. ## Write Policy ### Agent MAY write directly (no review): - `60-Learning/sessions/` — session summaries after substantial work - `60-Learning/patterns/` — recurring observations - `60-Learning/corrections/` — things that were wrong and got fixed - `60-Learning/inbox/` — candidates pending user review - `20-Projects/*.md` — status updates after concrete work - `30-Decisions/*.md` — when a clear decision was made ### Agent SHOULD write as DRAFT (`status: draft`): - `00-Telos/*.md` — identity, goals, constraints - `10-Preferences/*.md` — personal preferences, working style - `40-People/*.md` — person profiles (especially colleagues) - `70-Collaboration/*.md` — collaboration agreements ### Agent MUST NOT write: - Passwords, API keys, tokens, secrets - Intimate/private details without explicit consent - Speculative assumptions stated as facts - Full chat transcripts (use summaries, not raw dumps) ## Session-End Workflow After substantial work in a session: 1. Write session summary to `60-Learning/sessions/YYYY-MM-DD-{slug}.md` 2. If a decision was made → create/update `30-Decisions/` note 3. If project state changed → update `20-Projects/{project}.md` 4. If something new was learned → candidate in `60-Learning/inbox/` 5. Update `INDEX.md` if new notes were added 6. `git add -A && git commit -m "update: {description}" && git push` Not every session needs a summary. Only sessions that produced durable value. ## Language & Link Conventions - **Language**: German primary, English technical terms (match how Sascha communicates) - **Links**: Standard Markdown relative links (`[Text](relative/path.md)`) — works in Gitea AND Obsidian. Do not write Obsidian-only double-bracket links. - **Tags**: YAML frontmatter `tags:` list, not inline `#tag` - **Dates**: `YYYY-MM-DD` everywhere - **File naming**: `kebab-case.md` > **CRITICAL**: Current `AGENTS.md` and `SCHEMA.md` in the vault are canonical. If this skill disagrees with them, follow the vault files and patch the skill. ## Vault Structure ``` 00-Telos/ Who Sascha is, goals, constraints 10-Preferences/ Communication, tech-stack, working-style, do-don't 20-Projects/ Active project cards (state, next actions, decisions) 30-Decisions/ ADR-style decision records 40-People/ Colleagues, external contacts, family 50-Knowledge/ Reference knowledge (systems, concepts, companies) 60-Learning/ Session summaries, patterns, corrections 70-Collaboration/ How agents and human work together 80-Templates/ Note templates (project, decision, person, etc.) 90-Archive/ Completed/deprecated ``` ## Multi-Agent Compatibility This vault works with ANY agent (Hermes, Pi, OpenCode, Claude Code, Codex): - `AGENTS.md` at root = universal instructions (no agent-specific assumptions) - Agent identity stays in commit messages, not in note bodies - Multiple agents may read/write — last-writer-wins via Git - Sascha uses Pi + OpenCode on work laptop (with Basecamp CLI access) ### Agent-Hub skill deployment When Sascha asks whether this skill is in the AGENTS/agent-hub repo, verify `.agents/skills/shared-brain-vault/SKILL.md`; the Hermes-installed copy under `~/.hermes/skills/` is not enough for cross-agent use. If deploying it, copy the whole skill directory including `references/` and `scripts/`, stage only `.agents/skills/shared-brain-vault`, run the link audit and Agent-Hub checks, then commit without mixing pre-existing dirty Agent-Hub files. See `references/agent-hub-skill-deployment.md` for the command recipe and verification checklist. ## Initial Population Technique When populating the vault from scratch or doing a major migration: 1. **Extract context** from all available sources: - Hermes internal memory (`~/.hermes/memories/MEMORY.md`, `USER.md`) - Honcho peer card and user profile - Session search for key topics (5-10 queries covering all major projects) - Existing wikis (tech wiki, nemoti wiki) - Git repos for infrastructure details 2. **Compile into a single source file** at `/tmp/m3ta-brain-source/context.md` 3. **Dispatch parallel subagents** (up to 3), each handling distinct sections: - Agent A: Telos + Preferences + Collaboration - Agent B: Projects + Decisions + Knowledge - Agent C: People + Learning 4. Each subagent reads AGENTS.md + SCHEMA.md + context file, writes its files 5. **Merge, update INDEX.md, commit, push** See `references/km-landscape-research.md` for the research that informed this design (Karpathy LLM Wiki, Miessler PAI, qmd, Obsidian MCP integrations). See the vault's current link-audit command (documented in the `m3ta-brain` skill's `references/vault-map.md` when available, or in vault maintenance notes) after any vault population or restructuring. ## Relationship to Other Knowledge Stores | Store | Path | Purpose | Links | |---|---|---|---| | **m3ta-brain** (this) | `~/m3ta-brain` | Shared working memory | Standard Markdown relative links | | Tech Wiki | `/var/lib/hermes/wiki` | Research, concepts (EN) | Standard Markdown relative links | | Nemoti Wiki | `/var/lib/hermes/wiki-nemoti` | Lore, art strategy (DE) | Standard Markdown relative links | | Hermes Memory | `~/.hermes/memories/` | Hot cache, high-priority facts | N/A | | Session DB | Hermes internal | Raw transcripts | `session_search()` | **Rule**: Don't duplicate content across stores. m3ta-brain holds context and cross-references; research wikis hold detailed knowledge; Hermes memory holds hot facts for fast injection. ## Pitfalls - **Use standard Markdown links in m3ta-brain** — Gitea compatibility matters. This differs from older Obsidian-only guidance; current vault rules in `AGENTS.md` and `SCHEMA.md` are canonical. - **Don't dump raw chat transcripts** — write concise summaries with decisions, learnings, next actions. - **Don't create notes without cross-links** — minimum 2 internal Markdown links per note. Orphan notes break the graph. - **Don't write to 00-Telos or 10-Preferences without `status: draft`** — these are personal and need user review. - **Don't forget to `git push`** — the vault is useless if changes stay local. - **Don't confuse vault purposes** — m3ta-brain is working memory (state, decisions, learnings), not a research encyclopedia. For research, use the `research-intelligence` skill. - **People profiles are sensitive** — use `sensitivity: confidential` and `status: draft` for all person notes. Add colleagues only as information is learned through actual work. - **Subagents produce broken links** — after ANY parallel subagent population, run a Markdown-link audit and fix broken relative targets. Common errors: paths relative to vault root instead of the current file, placeholder example links, directory-only links with no target file, and ambiguous note names. - **`.gitkeep` is invisible in Obsidian** — use `README.md` instead for placeholder/directory-explanation content. Obsidian only shows `.md` files in the file explorer; hidden files are excluded. - **`execute_code` may be blocked in cron profiles** — run the link audit via `terminal`/`python3`, not via `execute_code`, if cron execution rejects Python tool calls. - **Dream Pass cron skill names can drift** — if a scheduled vault job reports `Skill(s) not found` for a vault-specific alias such as `m3ta-brain`, first list installed skills and update the cron to use the available class-level skill (`shared-brain-vault`) while keeping `~/m3ta-brain/AGENTS.md` and `~/m3ta-brain/SCHEMA.md` as canonical runtime instructions. Update both the cron `skills` field and any prompt text that tells the agent to load the missing skill; otherwise the next run may still be marked failed even if the task succeeds via fallback.