--- name: m3ta-brain description: "Shared Obsidian vault for human-agent collaboration. Use when: (1) Loading project context at session start (auto-recall), (2) Writing session summaries, decisions, project updates, or learning notes, (3) Searching for past decisions or project state, (4) Running nightly/weekly digest passes, (5) Creating or updating person profiles, (6) Any reference to 'the vault', 'shared brain', 'our context', 'what did we decide'. Triggers: m3ta-brain, shared brain, vault, session summary, decision note, project update, memory candidate, brain vault, auto-recall, digest, nightly pass." compatibility: opencode --- # m3ta-brain Shared Obsidian vault — the persistent, compounding working memory between Sascha and all AI agents. Git-versioned, standard Markdown, works in Obsidian and Gitea. ## Prerequisites - Vault cloned at `~/m3ta-brain` (resolves per-machine: `/var/lib/hermes/m3ta-brain` on m3-hermes, `/home/m3tam3re/m3ta-brain` on desktop, etc.) - Git configured with push access to `ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-brain.git` - Obsidian settings (auto-configured via `.obsidian/app.json`): Wikilinks OFF, relative paths ON Always pull before reading or writing: ```bash cd ~/m3ta-brain && git pull --rebase ``` ## Vault Structure (Quick Reference) See `references/vault-map.md` for full layout. Key directories: | Dir | Purpose | Write Access | |---|---|---| | `00-Telos/` | Identity, goals, constraints | Draft only | | `10-Preferences/` | Communication, tech stack, do's & don'ts | Draft only | | `20-Projects/` | Active project cards (state, next actions) | Direct | | `30-Decisions/` | Architecture Decision Records | Direct | | `40-People/` | Person profiles | Draft + confidential | | `50-Knowledge/` | Systems, concepts, companies | Direct | | `60-Learning/` | Sessions, patterns, corrections, inbox | Direct (inbox = candidates) | | `70-Collaboration/` | How-we-work, agent conventions | Draft only | | `80-Templates/` | Note templates | Read-only reference | --- ## Workflow 1: Session Start (Auto-Recall) **When:** At the beginning of any substantial work session, or when the user references past context. ### Step 1: Pull latest ```bash cd ~/m3ta-brain && git pull --rebase ``` ### Step 2: Read core context Read in this order (stop early if context is sufficient — do NOT read the entire vault): 1. `AGENTS.md` — the rules (skim if already known) 2. `INDEX.md` — dashboard, what's new, stats 3. `10-Preferences/do-dont.md` — hard rules to respect THIS session ### Step 3: Load project-specific context Determine the relevant project(s) from the user's message or working directory. Read only the relevant project cards: ``` 20-Projects/{project-slug}.md ``` If the topic is ambiguous, read `20-Projects/overview.md` for the dashboard. ### Step 4: Search for relevant history (optional, when deeper context needed) If qmd is installed: ```bash qmd query "{topic}" -c brain --md -n 5 ``` If qmd is NOT installed, use `search_files` on the vault directory: ``` search_files(pattern="{topic}", path="~/m3ta-brain", target="content") ``` ### Step 5: Recall relevant decisions For architectural or strategic questions, check recent decisions: ``` 30-Decisions/INDEX.md ``` ### Token budget Cap auto-recall to ~2000 tokens of injected context. Summarize rather than dumping full notes. --- ## Workflow 2: Session End (Persist Learnings) **When:** After substantial work — at minimum when explicitly asked, ideally proactively for any session that produced decisions, project changes, or learnings. ### Step 1: Write session summary File: `60-Learning/sessions/YYYY-MM-DD-{slug}.md` Use template `80-Templates/session-summary.md`. Fill all sections: ```yaml --- type: session-summary created: YYYY-MM-DD updated: YYYY-MM-DD session_date: YYYY-MM-DD projects: [] tags: [session] --- ``` Content sections: What We Discussed → Decisions Made → New Context Learned → Project Updates → Open Questions → Suggested Memory Candidates → Next Actions. ### Step 2: Create/update decision notes If a clear decision was made during the session, create `30-Decisions/YYYY-MM-{slug}.md` using the decision template. Link it from the project card. ### Step 3: Update project cards If project state changed, update the relevant `20-Projects/{project}.md`: Current State, Next Actions, Active Threads. ### Step 4: File memory candidates If something new was learned about the user, a person, or a pattern — write to `60-Learning/inbox/YYYY-MM-DD-{slug}.md` with `status: draft`. These get reviewed in the digest pass. ### Step 5: Commit and push ```bash cd ~/m3ta-brain git add -A git commit -m "session: {brief description} - {what was written/updated} - {key files}" git push origin main ``` --- ## Workflow 3: Decision Note **When:** A clear architectural, strategic, or process decision is made. File: `30-Decisions/YYYY-MM-{slug}.md` Required frontmatter: ```yaml --- type: decision created: YYYY-MM-DD updated: YYYY-MM-DD decided: YYYY-MM-DD decision_status: accepted # accepted | proposed | superseded impact: high # high | medium | low alternatives: [] tags: [decision] --- ``` Required sections: Context → Decision → Rationale → Consequences → Revisit When → Related. Update `30-Decisions/INDEX.md` with a new row. --- ## Workflow 4: Person Profile **When:** The user mentions a colleague, client, or contact with enough detail to warrant a profile. ### Rules - **sensitivity: confidential** for all person profiles - **status: draft** until the user confirms the content is accurate - Only write confirmed facts — mark speculation as `(unsicher)` - Do NOT create profiles for people mentioned in passing - Do NOT write sensitive personal details without explicit consent - Prefer the `60-Learning/inbox/` candidate workflow for new observations about existing people ### File location ``` 40-People/colleagues/{firstname-lastname}.md — work colleagues 40-People/external/{firstname-lastname}.md — external contacts 40-People/family.md — family (already exists) ``` ### When to add to an existing profile vs. write a new one - New person → new file - New observation about existing person → append to their profile under "Interaction History" - Pattern observed across multiple people → `60-Learning/patterns/` note instead --- ## Workflow 5: Nightly / Weekly Digest **When:** Run as a cronjob (daily or weekly). Can also be triggered manually. ### Purpose The vault accumulates drafts, candidates, and potentially stale information. The digest pass: 1. Consolidates inbox candidates 2. Promotes stable patterns 3. Flags stale projects 4. Reports broken links 5. Sends a summary to the user ### Step 1: Pull and scan ```bash cd ~/m3ta-brain && git pull --rebase ``` ### Step 2: Process inbox Read all files in `60-Learning/inbox/`. For each: - **Promote**: if the candidate is confirmed and stable → move to `60-Learning/patterns/` or update the relevant `10-Preferences/` note. Remove from inbox. - **Keep**: if still uncertain → leave in inbox with a `reviewed: YYYY-MM-DD` frontmatter field. - **Discard**: if proven wrong or stale → move to `90-Archive/`. ### Step 3: Check project freshness For each `20-Projects/*.md`, check the `updated` frontmatter field: - **> 30 days without update** → flag as "stale" in the digest report - **Next Actions all checked** → suggest moving to `90-Archive/` ### Step 4: Link health check Run a link audit script (see `references/vault-map.md` for the audit command). Report any broken links. ### Step 5: Update INDEX.md Refresh stats, recent decisions, recent sessions. ### Step 6: Commit and push ```bash git add -A git commit -m "digest: {date} pass - {N} inbox items processed - {N} patterns promoted - {N} stale projects flagged - {N} broken links found" git push origin main ``` ### Step 7: Report to user Send a concise digest message: ``` 📋 m3ta-brain Digest {date} - {N} neue Session-Summaries - {N} Inbox-Candidates verarbeitet ({promoted} promoted, {kept} kept) - {N} Decisions hinzugefügt - Projekte als stale markiert: {list} - Broken Links: {N} ``` ### Cronjob setup ``` schedule: "0 6 * * 1" # Weekly Monday 6am deliver: origin # back to chat skills: ["m3ta-brain"] prompt: "Run the m3ta-brain weekly digest pass. Follow the Nightly/Weekly Digest workflow in the m3ta-brain skill. Pull the vault, process inbox, check freshness, run link audit, commit, and report a concise summary." ``` --- ## Link Conventions **CRITICAL:** Use standard Markdown links with file-relative paths. NOT `[[wikilinks]]`. ```markdown [Project Name](project-name.md) [AZ-Gruppe](../20-Projects/az-gruppe.md) [Hermes](../../20-Projects/m3-hermes.md) ``` Rules: - File-relative paths only (`../dir/file.md`) - Always include `.md` extension - URL-encode spaces in filenames as `%20` (avoid spaces in filenames instead) - Minimum 2 internal links per note - Every note should be linked FROM at least one other note (no orphans) - Templates may contain `[[]]` placeholders — these are Obsidian template syntax, leave as-is --- ## Git Conventions ### Commit messages ``` session: {brief description} — after a work session decision: {slug} — new decision note update: {project} status — project card update digest: {date} pass — nightly/weekly digest fix: {what was fixed} — corrections add: {what was added} — new note or section ``` ### When to push - After writing session summaries or decision notes - After updating project cards - After digest passes - NOT after every single small edit — batch related changes ### Conflict handling If `git pull --rebase` fails: ```bash # Check what conflicted git status # Resolve manually, then: git add -A && git rebase --continue ``` Do NOT force-push. The vault is shared — last-writer-wins via normal Git. --- ## What NOT to Do - **Do NOT** write secrets, passwords, API keys, or tokens to the vault - **Do NOT** write intimate/private details without explicit consent - **Do NOT** create profiles for people mentioned only in passing - **Do NOT** dump full chat transcripts — use summaries - **Do NOT** use `[[wikilinks]]` — they don't render in Gitea - **Do NOT** assume facts — mark speculation as `(unsicher)` or `status: draft` - **Do NOT** duplicate content from the Tech Wiki or Nemoti Wiki — link to them instead - **Do NOT** modify `80-Templates/` during a session — they are structural - **Do NOT** force-push (`git push --force`) — the vault is shared --- ## Relationship to Other Systems | System | Role | When to use | |---|---|---| | m3ta-brain (this vault) | Shared working memory, project context, decisions, learnings | Session start, session end, decisions | | Hermes internal memory | Hot cache of critical facts for fast recall | Automatic, small entries only | | Tech Wiki (`/var/lib/hermes/wiki`) | Research, concepts, entities (English) | Deep research, new technology | | Nemoti Wiki (`/var/lib/hermes/wiki-nemoti`) | Lore, characters, art strategy (German) | Nemoti creative work | | Session Search | Raw session transcripts | "What did we do about X?" | | qmd | Hybrid search across vaults (if installed) | Cross-vault semantic queries | | Agent Hub | Cross-agent task coordination | Beads task queue | Rule: **m3ta-brain is the working context layer.** Research goes to Tech Wiki. Lore goes to Nemoti Wiki. Raw session history stays in session search. m3ta-brain holds the glue: decisions, project state, preferences, learnings, people. --- ## Multi-Agent Compatibility This vault is designed for ANY agent (Hermes, Pi, OpenCode, Claude Code, Codex). Rules: - No agent-specific assumptions in note content - Agent identity stays in commit messages, not in note bodies - Multiple agents may read/write — last-writer-wins via Git - The vault is the single source of truth — agent-internal memory is a cache - If another agent made changes, `git pull` before writing --- ## Pitfalls - **Forgetting to pull**: Always `git pull --rebase` before reading or writing. The vault may have been updated by another agent or by Sascha from another device. - **Using wikilinks**: `[[wikilinks]]` do NOT render as links in Gitea. Always use `[Text](relative/path.md)`. - **Wrong relative paths**: Links must be relative FROM the source file, not from vault root. From `30-Decisions/X.md` to `20-Projects/Y.md` → `../20-Projects/Y.md`. - **Overwriting drafts**: `00-Telos/`, `10-Preferences/`, `40-People/` are `status: draft`. Do not overwrite without explicit user confirmation. - **INDEX.md drift**: When adding notes, update `INDEX.md` in the same commit. Stale indexes defeat the purpose. - **Orphan notes**: Every note must be linked FROM at least one other note. Unlinked notes are invisible in the graph. - **External wiki duplication**: Do not copy Tech Wiki or Nemoti Wiki content into m3ta-brain. Summarize and link: `[Tech Wiki: Nix CLI](/var/lib/hermes/wiki/concepts/nix-cli-migration.md)`.