m3tam3re/AGENTS
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add: m3ta-brain skill — shared vault workflows

Browse Source 
Skill for the m3ta-brain Obsidian vault (ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-brain.git).
Agent-agnostic — works with Hermes, Pi, OpenCode, Claude Code.

Workflows:
1. Session Start (Auto-Recall): pull, read core context, load project state
2. Session End: write summary, decisions, project updates, memory candidates
3. Decision Note creation (ADR-style)
4. Person Profile creation (with sensitivity rules)
5. Nightly/Weekly Digest: process inbox, check freshness, link audit, report

Conventions:
- Standard Markdown links with relative paths (NOT wikilinks)
- Git commit/push patterns
- Write policy (direct vs draft vs forbidden)
- Relationship to Tech Wiki, Nemoti Wiki, qmd, session search

References:
- vault-map.md: full directory layout, tag taxonomy, link audit command
This commit is contained in:
m3ta-chiron
2026-06-29 20:55:12 +02:00
parent 920c00313a
commit 6fac485813
2 changed files with 541 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/m3ta-brain/SKILL.md
+392
View File
@@ -0,0 +1,392 @@
---
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 `/var/lib/hermes/workspace/m3ta-brain` (server) or local machine
- 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 /var/lib/hermes/workspace/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 /var/lib/hermes/workspace/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="/var/lib/hermes/workspace/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 /var/lib/hermes/workspace/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 /var/lib/hermes/workspace/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
<!-- Same directory -->
[Project Name](project-name.md)
<!-- Cross-directory (from 30-Decisions/ to 20-Projects/) -->
[AZ-Gruppe](../20-Projects/az-gruppe.md)
<!-- Cross-directory (from 60-Learning/patterns/ to 20-Projects/) -->
[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)`.
skills/m3ta-brain/references/vault-map.md
+149
View File
@@ -0,0 +1,149 @@
# Vault Map — m3ta-brain Structure Reference
> Full directory layout with purpose and content guidelines for each section.
## Root Files
| File | Purpose |
|---|---|
| `AGENTS.md` | Universal agent instructions: read order, write policy, conventions |
| `SCHEMA.md` | Frontmatter types, tag taxonomy, naming conventions, quality rules |
| `README.md` | Human-facing intro and quick-start guide |
| `INDEX.md` | Dashboard: stats, active projects, recent decisions, recent sessions |
| `.obsidian/app.json` | Obsidian settings: Wikilinks OFF, relative paths ON |
| `.gitignore` | Ignores workspace state, OS files, sync conflicts |
## Directory Detail
### 00-Telos/ (Identity)
| File | Content | Write Rule |
|---|---|---|
| `sascha.md` | Identity card: name, role, tech background, traits, motivation | Draft only |
| `goals.md` | Professional + personal goals with timeframes | Draft only |
| `constraints.md` | Hard constraints: team skills, budget, self-hosting, security | Draft only |
### 10-Preferences/ (How Sascha Works)
| File | Content | Write Rule |
|---|---|---|
| `communication.md` | Communication style: terse text, modality matching, language | Draft only |
| `tech-stack.md` | Full tech stack organized by category | Draft only |
| `working-style.md` | Delegation vs oversight, test-driven infra, iterative debugging | Draft only |
| `do-dont.md` | Explicit Do's and Don'ts table — HARD RULES | Draft only |
### 20-Projects/ (Active Work)
| File | Content | Write Rule |
|---|---|---|
| `overview.md` | Dashboard table of all projects with status/priority | Direct |
| `az-gruppe.md` | CTO role, Bestellungs-Pipeline, Appsmith, K8s | Direct |
| `nemoti.md` | Nemoti art support, YouTube/TikTok/Twitch/Website | Direct |
| `m3ta-home.md` | Portable NixOS profile framework | Direct |
| `m3-hermes.md` | Hermes Agent, Matrix gateway | Direct |
| `honcho.md` | Honcho self-hosting on m3-atlas | Direct |
| `hermes-nixos-setup.md` | Livestream + Blogpost standalone repo | Direct |
| `agent-hub.md` | Cross-agent coordination, Beads task queue | Direct |
| `infrastructure.md` | Server overview, domains, services | Direct |
### 30-Decisions/ (ADR-style)
| File | Content |
|---|---|
| `INDEX.md` | Table of all decisions sorted by date |
| `YYYY-MM-{slug}.md` | Individual decision records |
Each decision note has: Context → Decision → Rationale → Consequences → Revisit When → Related.
### 40-People/ (Contacts)
| File/Dir | Content | Sensitivity |
|---|---|---|
| `INDEX.md` | Index of all people | Internal |
| `family.md` | Nemoti profile | Confidential |
| `colleagues/README.md` | Placeholder + guidance for colleague profiles | Internal |
| `colleagues/{name}.md` | Individual colleague profiles | Confidential |
| `external/{name}.md` | External contacts | Internal |
### 50-Knowledge/ (Reference)
| Dir | Content |
|---|---|
| `systems/` | Infrastructure systems (Traefik, Netbird, Authentik, etc.) |
| `concepts/` | Methods, patterns, frameworks |
| `companies/` | Organization profiles |
### 60-Learning/ (Accumulated Wisdom)
| Dir | Content | Write Rule |
|---|---|---|
| `sessions/` | Session summaries (YYYY-MM-DD-slug.md) | Direct |
| `patterns/` | Recurring observations about work habits, preferences | Direct |
| `corrections/` | Things that were wrong and got fixed | Direct |
| `inbox/` | Candidates pending review (drafts before promotion) | Direct |
### 70-Collaboration/ (Working Agreement)
| File | Content | Write Rule |
|---|---|---|
| `how-we-work.md` | Delegation model, when to ask vs decide, session workflow | Draft only |
| `agent-conventions.md` | Rules for any agent working in this vault | Draft only |
| `multi-agent-setup.md` | How Pi/OpenCode/other agents use the vault | Draft only |
### 80-Templates/ (Note Templates)
Read-only reference. Contains: `project.md`, `decision.md`, `person.md`, `session-summary.md`, `learning.md`.
### 90-Archive/ (Deprecated)
Completed projects, superseded decisions, discarded candidates.
## Link Audit Command
To check for broken links across the vault:
```bash
python3 -c "
import os, re
from collections import defaultdict
VAULT = '/var/lib/hermes/workspace/m3ta-brain'
md_files = []
for root, dirs, files in os.walk(VAULT):
if '.git' in root or '.obsidian' in root: continue
for f in files:
if f.endswith('.md'):
md_files.append(os.path.relpath(os.path.join(root, f), VAULT))
# Build index
paths = set(md_files)
broken = []
for f in md_files:
with open(os.path.join(VAULT, f)) as fh:
for i, line in enumerate(fh, 1):
for m in re.finditer(r'\[([^\]]+)\]\(([^)]+\.md)\)', line):
target = m.group(2)
if target.startswith('http'): continue
resolved = os.path.normpath(os.path.join(os.path.dirname(f), target))
if resolved not in paths:
broken.append((f, i, target))
print(f'Broken links: {len(broken)}')
for f, i, t in broken:
print(f' {f}:{i} → {t}')
"
```
## Tag Taxonomy (from SCHEMA.md)
| Tag | Use for |
|---|---|
| `infrastructure` | Servers, domains, networks, services |
| `nixos` | NixOS/Flakes/Nix-related |
| `work` | AZ-Gruppe / AZ-Intec related |
| `creative` | Nemoti art, music, lore |
| `decision` | Architecture/system decisions |
| `agent` | AI agent infrastructure |
| `security` | Security-relevant info |
| `process` | How-we-work conventions |
| `person` | Person profiles |
| `deprecated` | No longer current |