ObsiClaw

Multi-agent coordination layer for Obsidian-based personal knowledge management.

The Problem

AI agents share a vault. They corrupt each other's writes.

When you run an always-on agent runtime (OpenClaw) alongside on-demand Claude Code sessions, both writing to the same Obsidian vault — you get race conditions. OpenClaw's own issue tracker documents this: ~15% collision rate per cron cycle, compaction breaking concurrent edits. Two agents read a file, both write back, one silently overwrites the other. No error, no merge conflict — just data loss that you discover days later when the missing context matters.

Nobody else solves this. Existing vault templates (obsidian-mind, obsidian-second-brain) assume single-agent use. They offer excellent workflows for one agent operating in isolation, but provide no coordination primitives for the moment a second agent enters the picture.

Architecture

flowchart TB
    subgraph Agents
        OC["OpenClaw<br/>(always-on runtime)"]
        CC["Claude Code<br/>(on-demand sessions)"]
    end

    subgraph Vault["Obsidian Vault (~/vault)"]
        BF["Brain Files<br/>SOUL · USER · NOW · MEMORY"]
        WB[".write-back/<br/>Staging Files"]
        LK[".write-lock.d/<br/>Write Locks"]
    end

    subgraph Coordination["Coordination Layer"]
        SM["Section Markers<br/>targeted edits"]
        SP["Staging Protocol<br/>safe proposals"]
        WL["Write Locks<br/>mutual exclusion"]
        CH["Coherence Check<br/>cross-reference validation"]
    end

    CC -- "session ends" --> WB
    OC -- "heartbeat fires" --> SP
    WB --> SP
    SP --> WL
    WL --> SM
    CH -- "validate" --> SM
    SM -- "merge into NOW.md" --> BF

    style Vault fill:#1a1a2e,stroke:#e94560,color:#eee
    style Coordination fill:#0f3460,stroke:#e94560,color:#eee
    style Agents fill:#16213e,stroke:#e94560,color:#eee

Loading

What Makes This Different

1. Section-marker merge convention — HTML comment markers delineate independently addressable regions in vault files, so agents edit sections without touching the rest. See Write Safety Primitives.
2. Staging-file write protocol — on-demand sessions never write to brain files directly; they propose changes via YAML-frontmatter staging files that queue for merge. See Write Safety Primitives.
3. Atomic write locks — mkdir-based locks provide mutual exclusion during the merge window, preventing concurrent heartbeat collisions. See Write Safety Primitives.
4. Coherence checking — automated cross-referencing catches drift between active focus items and recent completions, surfacing contradictions before they compound. See Why This Architecture.
5. Vault bridge — a symlink + rules file pattern gives every project on the machine read access to shared context, ending the "blank slate every session" problem. See Cross-Project Context.
6. Vault health check — /vault-health command checks brain files, section markers, staging queue, heartbeat freshness, and write lock status without needing an infrastructure manifest. See the command
7. Signal filtering — smart priority filtering across all signal sources (Slack, email, GitHub, Jira). Reads active context before surfacing, groups related signals, skips noise.
8. Ambient learning — raw/ watcher cross-references new saves against the full vault (projects, people, content seeds, tasks, artifacts) and surfaces connections automatically.
9. Meeting prep — proactive attendee context loading. When a meeting is upcoming, loads people files and recent interactions to generate talking points.
10. Project/task freshness checks — detects drift between NOW.md state and project/task files. Flags stale entries without auto-editing.
11. Self-improvement loop — .learnings/ directory captures errors, timeouts, and recurring patterns from heartbeat cycles. Promotes learnings to config files after 3+ recurrences.
12. Daily note auto-generation — morning briefs auto-create logs/YYYY-MM-DD.md with yesterday's completions, today's calendar, and active focus areas.
13. People reconnect tracking — tracks last-contact and reconnect-interval in people files, nudges when reconnect is overdue.

Quick Start

git clone https://github.com/sakhnenkoff/obsiclaw.git
cd obsiclaw
./setup.sh

# Optional: install vault-bridge globally (loads brain files in every project)
./setup.sh --global

ObsiClaw is organized in three layers:

• core/ — Agent instructions, heartbeat config, and vault infrastructure (AGENTS.md, HEARTBEAT.md, staging/lock support). The coordination primitives that make multi-agent setups safe.
• starter/ — Brain file templates (SOUL.md, USER.md, NOW.md, MEMORY.md), vault structure guide, and Obsidian canvas. The starting point for a new vault.
• commands/ — Ten slash commands (/today, /closeday, /sync, /capture, /new, /lint, /vault-health, /schedule, /process-inbox, /research) that automate daily vault workflows.

Use ./setup.sh --core-only to install just the coordination layer without starter templates or commands — useful if you already have a vault and only need the write safety primitives.

How It Works

A write cycle flows through six steps:

1. Session ends — A Claude Code session produces a staging file in .write-back/, containing proposed changes as YAML frontmatter (target file, section, action) plus the content to merge.
2. Heartbeat fires — The always-on runtime's periodic heartbeat detects pending staging files and acquires a write lock (mkdir .write-lock.d — atomic on all filesystems).
3. Read and validate — Staging files are read and their YAML frontmatter is validated: target file must exist, section must be defined, action must be recognized.
4. Section-aware merge — Content is inserted into the target file at the correct section marker boundaries. Only the targeted section is modified; the rest of the file is untouched.
5. Coherence check — Cross-references active focus items against recent completions. Flags contradictions (e.g., a task marked both active and completed) and stale entries.
6. Release lock — The lock directory is removed, staging files are cleaned up, and the vault is back to a consistent state ready for the next cycle.

Comparison

Capability	ObsiClaw	obsidian-mind	obsidian-second-brain	Raw OpenClaw
Write coordination
Section-marker merge convention	Yes	No	No	No (#53712)
Staging-file write protocol	Yes	No	No	No
Atomic write locks	Yes	No	No	No (#63922)
State management
Coherence checking	Automated	Weekly manual	Manual command	No
Proactivity levels	3 levels	No	No	No
Vault bridge (cross-project)	Yes	No	No	No (#64097, #63829)
Identity & memory
Brain files	4 files	6 files	3 files	4 files
Memory consolidation	Automated daily consolidation	No	Manual reconcile	Yes
Automation
Working heartbeat/cron	Yes	No	Documented, scheduler not included	Yes (basic)
Session hooks	Via OpenClaw	5 Python hooks	1 shell hook	Built-in
Vault skills
Commands shipped	10 core	18	25	N/A
Thinking tools	Roadmap	No	Yes	No
Performance review tools	No	Yes	No	No

Brain file patterns originated in OpenClaw. obsidian-mind excels at performance review workflows. obsidian-second-brain has excellent thinking tools. ObsiClaw's contribution is the coordination layer that makes multi-agent setups safe. Competitor data verified April 2026 — star counts and feature sets may change.

Methodology

• Why This Architecture — brain files, single-writer model, coherence checking, proactivity
• Write Safety Primitives — section markers, staging protocol, write locks
• Cross-Project Context — symlink pattern, context loading, write-back loop
• Periodic Autonomy — heartbeat modes, signal scanning, buddy tone

Credits

• OpenClaw for brain file patterns and the heartbeat concept
• obsidian-mind for performance review workflow patterns
• obsidian-second-brain for thinking tools inspiration

License

MIT — see LICENSE.