AGENTS/skills/shared-brain-vault/SKILL.md

name, description, compatibility

name	description	compatibility
shared-brain-vault	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'.	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.