The missing governance layer for AI agents
Lobsidian is a file-based governance and coordination protocol for AI agents operating in a shared Markdown vault. It defines how agents are authorized, how they communicate, what they may do, and how every action is recorded for human review. Lobsidian sits at Layer 2.5 -- between MCP (tool access) and A2A (agent-to-agent communication) -- providing the persistent, human-readable workspace that neither protocol addresses. No vendor lock-in: any agent that can read and write Markdown files can participate.
| Layer | Protocol | Role |
|---|---|---|
| 4 | A2UI | Agent-to-User interfaces |
| 3 | A2A (Google / Linux Foundation) | Task delegation between agents |
| 2.5 | Lobsidian | Persistent, human-readable, version-controlled governance workspace |
| 2 | MCP (Anthropic / AAIF) | Tool access |
| 1 | LLM Providers | Model inference |
| 0 | Transport | HTTP, stdio, SSE |
Lobsidian does not compete with MCP or A2A. It fills the gap between them: a durable, auditable layer where governance state lives as plain files under version control.
Current agent frameworks solve execution. None of them solve governance.
- Visibility -- "What did my agent do while I was sleeping?" Today the answer is buried across framework-specific logs, tool call traces, and chat transcripts. Lobsidian writes every significant action to append-only Markdown logs in a single vault.
- Control -- "How do I set boundaries without writing code?" Agents operate under policies expressed as Markdown files with structured frontmatter. Edit a file, change the rules. No redeployment, no API calls.
- Accountability -- "Who authorized this action?" Every Lobsidian action traces back through a delegation chain to a human decision. Agents cannot self-authorize. Trust is granted incrementally and revoked instantly.
Existing agent frameworks solve execution but not governance. Lobsidian fills this gap.
| Aspect | Traditional Agent Setup | Lobsidian |
|---|---|---|
| Configuration | Framework-specific formats (CLAUDE.md, cartridge YAML, JSON configs) | Universal Agent-Flavored Markdown -- any framework that reads files can participate |
| Governance | Ad-hoc system prompts, binary allow/deny | Sociocracy 3.0: drivers, domains, consent tiers, delegation chains |
| Trust model | Static permissions set at deploy time | Dynamic Trust Ladder (Shadow, Suggest, Act & Report, Autonomous) |
| Human oversight | All-or-nothing approval | Four consent tiers: observe, auto, async, sync |
| Audit trail | Logs scattered across framework-specific stores | Event-sourced append-only action logs with provenance chains |
| Multi-agent coordination | Framework-specific message passing or custom APIs | Vault-as-blackboard: agents read/write shared Markdown files |
| Privacy | Varies by implementation | GDPR metadata built into every record schema |
| Portability | Locked to one framework's ecosystem | Switch frameworks without losing governance state or history |
- First open protocol applying S3 organizational patterns to AI agent governance. Sociocracy 3.0's consent-based decision-making, domain-scoped authority, and objection-seeking processes are adapted for human-agent and agent-agent coordination.
- Trust is earned incrementally and revoked instantly. Agents climb a trust ladder through demonstrated competence. A single policy violation drops them back to observation mode.
- Every agent traces authority back to a human through delegation chains. No agent can self-authorize. The provenance of every permission is recorded and auditable.
- Agreements are treated as time-bound experiments with review dates. Governance decisions carry expiration dates and are revisited, not assumed permanent.
- Tensions (observed gaps between the current state and what is needed) drive system evolution. Changes to governance originate from documented observations, not ad-hoc modifications.
Lobsidian applies six governance patterns from Sociocracy 3.0 (S3) to AI agent management. Each pattern maps to concrete file structures and runtime behaviors defined in Section 4 of the spec.
| Concept | S3 Origin | What It Does in Lobsidian |
|---|---|---|
| Drivers | Organizational Driver | The formalized "why" behind every agent. Described as current conditions + effect + relevance. If the driver is resolved, the agent should be retired. |
| Domains | Domain of Responsibility | The permissions manifest: what an agent MAY perceive, decide, and execute. Includes hard constraints (YAML: tool whitelists, rate limits) and soft governance (Markdown: behavioral guidelines). |
| Consent Tiers | Consent Decision-Making | 4 levels: Observe (read-only), Auto (routine, logged), Async (proposals, human reviews), Sync (blocks until human approves). "Good enough for now, safe enough to try." |
| Trust Ladder | Evaluate and Evolve | 4 dynamic levels: Shadow, Suggest, Act & Report, Autonomous. Trust earned over weeks, lost in one incident. Agents cannot self-promote. |
| Delegation Chains | Delegate Influence | Every agent carries a delegation_chain tracing accountability back to a human. First entry must be human. Chain depth should not exceed 3. |
| Tensions | Navigate via Tension | Agents create structured observations when they detect gaps between current and desired state. Tensions drive governance evolution. |
Hard governance (YAML frontmatter) defines the walls -- tool whitelists, path restrictions, rate limits. Soft governance (Markdown body) defines the culture within those walls -- communication style, escalation preferences, domain-specific SOPs. Both live in the same file.
vault/
├── .protocol/ # Protocol metadata (version, schemas, glossary) [REQUIRED]
│ ├── version.md # Protocol version (semver) + vault-wide defaults
│ ├── paths.md # Custom directory mapping (optional overlay support)
│ ├── glossary.md # Shared vocabulary for agents and humans
│ └── schema/ # JSON schemas for frontmatter validation (15 schemas)
│
├── 00-governance/ # S3 Logbook: organization driver, policies, delegation log
│ ├── organization-driver.md
│ ├── agreements/ # Consent-based agreements (with review dates)
│ ├── policies/ # Standing operational rules (privacy, escalation, retention)
│ └── delegation-log.md
│
├── 10-agents/ # Agent definitions (agent.md + driver.md + domain.md per agent)
│ ├── _registry.md # MOC: index of all agents with status and trust level
│ └── {agent-name}/ # Per-agent directory
│ ├── agent.md # Identity + instructions (analogous to A2A Agent Card)
│ ├── driver.md # S3 Driver: why this agent exists
│ ├── domain.md # S3 Domain: permissions, constraints, trust level
│ ├── skills/ # Agent Skills Standard compatible
│ └── memory/ # Agent-specific persistent memory
│
├── 20-inbox/ # Capture layer (email, messages, webhooks, triage)
│ ├── email/
│ ├── messages/
│ ├── webhooks/
│ ├── human/
│ └── triage/ # Processing staging: drivers/, proposals/, handoffs/
│
├── 30-projects/ # Active projects (PARA)
├── 40-areas/ # Ongoing responsibilities (PARA)
├── 50-resources/ # Reference material (PARA)
│
├── 60-logs/ # Audit trail: actions, decisions, reviews, tensions, daily notes
│ ├── actions/ # Per-action audit entries (append-only)
│ ├── decisions/ # Decision records with rationale
│ ├── reviews/ # Periodic agent/agreement reviews
│ ├── tensions/ # S3 "Navigate via Tension" records
│ └── daily/ # Daily summary projections
│
├── 70-archive/ # Completed/retired items (PARA lifecycle end)
│ └── agents/, projects/, drivers/, agreements/
│
├── 80-templates/ # 10 file templates for all record types
│
└── 90-meta/ # Vault-about-vault
├── SOUL.md # Vault personality/philosophy
├── USER.md # Human operator profile(s)
├── HEARTBEAT.md # Periodic task schedule
└── TOOLS.md # Available tools and environment config
Tens-based Johnny Decimal numbering provides 9 insertion slots between categories. .protocol/ is hidden infrastructure (like .git/). Directory layout is customizable via .protocol/paths.md -- Lobsidian overlays existing vaults without forced restructuring.
Lobsidian defines 13 canonical record types. Every file's type frontmatter field must be one of these values. Full schemas are in Section 5.3 of the spec and validated by JSON schemas in .protocol/schema/.
| Type | Purpose | Status Lifecycle |
|---|---|---|
agent |
Agent identity + instructions | active / paused / retired |
driver |
Why something exists (S3) | active / resolved / superseded |
domain |
Permissions manifest (S3) | active / under-review / suspended / retired |
task |
Actionable commitment | open / in-progress / blocked / done / cancelled |
decision |
Governance decision record | proposed / active / superseded / revoked |
policy |
Standing operational rule | draft / active / under-review / superseded / revoked |
agreement |
Cross-domain coordination | proposed / active / expired / revoked |
message-event |
Captured communication | unprocessed / processed / archived |
conversation |
Thread/event bundle | active / resolved / archived |
action-log |
Agent action audit entry | completed / failed / reverted (append-only) |
tension |
Systemic issue observation | open / acknowledged / resolved / dismissed |
proposal |
Action requiring approval | pending / approved / rejected / amended / withdrawn |
daily-note |
Daily summary projection | current / archived |
Every file carries mandatory frontmatter: id, type, status, created, updated, source, provenance, and access.
Lobsidian is tool-agnostic. Any agent that can read and write Markdown files can participate. The protocol does not require any specific framework, LLM provider, or runtime.
| Framework | Integration Method | Bootstrap File |
|---|---|---|
| Claude Code / NanoClaw | CLAUDE.md with Lobsidian bootstrap instruction | CLAUDE.md |
| OpenClaw | AGENTS.md + workspace mapping | AGENTS.md |
| NanoBot | YAML cartridge referencing vault path | cartridge.yml |
| PicoClaw | JSON config with vault_path |
config.json |
| Any framework | Raw file I/O (read/write Markdown) | Any instruction file |
The bootstrap instruction directs agents to read their domain file at 10-agents/{agent-name}/domain.md on startup. Full examples for each framework are in Appendix B of the spec.
Lobsidian requires only Tier 1 access (raw file I/O). MCP servers and Obsidian plugins are convenience layers, not requirements. If your agent can read a file and write a file, it can run Lobsidian.
# Clone the starter vault
git clone https://github.com/cannuri/lobsidian.git my-vault
cd my-vault
# Validate the vault
cd cli
npm install
npm test # 34 tests, all passing
npx ts-node src/index.ts .. # Run against the vaultExpected output:
Lobsidian Validator v0.1.0
Checking vault at: /path/to/my-vault
✓ Check 1: All files have valid YAML frontmatter with mandatory fields
✓ Check 2: All id values are unique
✓ Check 3: All type values are canonical
✓ Check 4: All status values are valid for their type
✓ Check 5: All date fields are valid ISO 8601
✓ Check 6: All provenance entries resolve
✓ Check 7: All wikilinks in provenance resolve
✓ Check 8: Every task links to provenance
✓ Check 9: Every action-log links to agent and domain
✓ Check 10: Proposals with requireApproval have isApproved
✓ Check 11: All file names follow naming conventions
✓ Check 12: .protocol/ directory exists with version.md
✓ Check 13: Every agent has valid delegation_chain
✓ Check 14: Every domain references a primary driver
Results: 0 errors, 0 warnings
- Create the agent directory:
mkdir -p 10-agents/my-agent/memory- Copy and customize templates:
cp 80-templates/agent.md 10-agents/my-agent/agent.md
cp 80-templates/driver.md 10-agents/my-agent/driver.md
cp 80-templates/domain.md 10-agents/my-agent/domain.md-
Edit each file to set
agent_id,delegation_chain,trust_level,allowed_tools, and other fields relevant to your agent's role. -
Register the agent in
10-agents/_registry.md. -
Record the delegation in
00-governance/delegation-log.md. -
Validate:
npx ts-node cli/src/index.ts .| Level | Requirements | Use Case |
|---|---|---|
| Minimal | .protocol/ + version.md + 1 agent with delegation_chain |
Overlay on existing vault |
| Standard | Full directory structure + driver/domain per agent + action logging + HEARTBEAT.md |
Active single-operator deployment |
| Full | Complete S3 governance + trust history + GDPR metadata + all 14 validation checks | Compliance-critical, multi-agent |
The CLI validates 14 checks against the vault:
| # | Check |
|---|---|
| 1 | Valid YAML frontmatter with mandatory fields |
| 2 | Unique IDs across the vault |
| 3 | Canonical type values (13 types) |
| 4 | Valid status values per type |
| 5 | ISO 8601 date formats |
| 6 | Provenance entries resolve |
| 7 | Wikilinks in provenance resolve |
| 8 | Tasks link to provenance |
| 9 | Action-logs link to agent and domain |
| 10 | Proposals have approval fields |
| 11 | Kebab-case file naming |
| 12 | .protocol/ directory exists |
| 13 | Agents have human delegation chains |
| 14 | Domains reference active drivers |
| Deliverable | Status |
|---|---|
Specification document (spec.md) |
Done |
| Starter vault with full directory structure | Done |
| 15 JSON schemas for frontmatter validation | Done |
| 10 Markdown templates for all record types | Done |
| Example email-triage agent with S3 governance | Done |
| Validation CLI (14 checks, 34 tests) | Done |
CONTRIBUTING.md with S3-based governance |
Done |
| Version | Focus |
|---|---|
| v0.1 | Draft spec, starter vault, schemas, CLI validator |
| v0.5 | Community review, GitHub Actions, bootstrap files for 2+ frameworks |
| v1.0 | Public release, full schema coverage, 4+ framework bootstraps |
| v1.1 | Multi-user: git worktrees, OVADARE integration, multi-vault federation |
- Join us on Discord
- See CONTRIBUTING.md for the S3-based governance process.
- Issues use the tension template: observation, current state, desired state, suggested response.
- PRs are approved by consent (no reasoned objections), not vote count.
TBD
- Sociocracy 3.0 by James Priest, Bernhard Bockelbrink, Liliana David
- PARA method by Tiago Forte
- Johnny Decimal by Johnny Noble
- Agent Skills Standard by the Agentic AI Foundation
- Research synthesis from ChatGPT, Claude, Gemini, and Perplexity analyses