Lobsidian

Structured accountability for AI agents. Plain markdown files that are simultaneously the agent's memory and the team's knowledge base.

Quick Start

npx lobsidian init ./my-project

That's it. Open my-project/Start Here.md to see what was created, or point an AI agent at my-project/_lobsidian/AGENT.md and it immediately knows how to operate.

To install globally:

npm install -g lobsidian

Requires Node.js 18+.

Why Lobsidian?

Existing AI memory tools (Mem0, Zep, Letta) solve what an agent can recall. Lobsidian solves what an agent is accountable for -- who delegated that authority, and how improvements surface.

Give an AI agent access to files and it will do things. But:

• Who said it should? No record of why work was started or who approved it.
• Is it working? No success criteria, no review dates, no feedback loop.
• What's the scope? Agents drift. Without boundaries, they reorganize your entire vault.
• Where's the audit trail? Actions happen, but the reasoning disappears with the conversation.

Lobsidian fixes this with a simple protocol: every piece of work traces a chain from motive (why) to decision (what, with human consent) to task (concrete work, with outcome). Decisions carry review dates, closing the loop.

How It Works

MOTIVE (why)         "Website is slow, losing visitors"
    |
DECISION (what)      "Implement CDN caching"
    |                 success_criteria: "Lighthouse > 90"
    |                 review_date: 2026-05-20
    |                 status: proposed -> [human consents] -> active
    |
TASK (work)          "Configure CloudFront distribution"
    |                 assignee: my-agent
    |                 outcome: "Lighthouse 94, load time 1.4s"
    |
REVIEW               Is the motive still relevant?
                      Did the decision meet its criteria?

Every file is a markdown file with YAML frontmatter. Frontmatter is the API. Folders are human convenience.

Usage

Create a Vault

lobsidian init ./my-project

The path is where Lobsidian creates the vault structure. Use any directory -- ./my-project, /path/to/vault, or . for the current directory.

Options:

• --name "My Project" -- vault display name (defaults to directory name)
• --agent "my-agent" -- default agent name (defaults to "agent")

This creates:

my-project/
  _lobsidian/           # System files (agent skill, config, templates, procedures)
  Motives/              # Why something needs attention
  Decisions/            # What was decided and why
  Tasks/                # Concrete work items
  Knowledge/            # Reference material and notes
  Journal/              # Chronological entries
  Inbox/                # Unprocessed items
  Archive/              # Completed items (nothing is deleted)
  Start Here.md         # Orientation guide
  .gitignore

Validate a Vault

lobsidian validate ./my-project
# OK  7 files checked, 0 errors, 0 warnings

lobsidian validate ./my-project --fix    # Auto-fix: stale claims, orphaned tasks
lobsidian validate ./my-project --json   # Machine-readable output

21 checks covering frontmatter schemas, broken wiki-links, circular references, consent bypasses, overdue reviews, and more.

Connect an Agent

Agent Skills (recommended): If your platform supports Agent Skills, Lobsidian ships a skill file at skills/lobsidian/SKILL.md. No extra configuration needed -- the agent discovers it automatically.

Manual one-liner:

lobsidian init ./my-project --print-shim

Outputs a shim you can paste into your agent's startup context (e.g. CLAUDE.md, .cursorrules).

Direct context injection: Load _lobsidian/AGENT.md (~1,500 tokens) into the agent's system prompt or context window. Set LOBSIDIAN_AGENT_NAME env var for identity.

Integration Contract

• File access: read/write to the vault directory (plain markdown files only)
• Startup context: load _lobsidian/AGENT.md (~1,500 tokens) at agent startup
• Quick setup: lobsidian init --print-shim outputs a one-liner for agent config files

What Makes This Different

No infrastructure. No databases, no servers, no vector stores. Just markdown files on disk. Works offline. Works with git.

Self-documenting agents. An agent reads one file (_lobsidian/AGENT.md, ~1,500 tokens) and knows the entire protocol. No training, no fine-tuning, no SDK integration.

Consent gates. Agent-created decisions start as draft or proposed. An agent cannot set status: active on its own decisions -- human consent is a hard requirement, not a suggestion.

Review cycles. Every decision carries a review_date and success_criteria. When the date arrives, the agent surfaces the review. This is the feedback loop that most AI systems lack entirely.

Domain boundaries. Each agent operates within a defined domain -- a set of filesystem paths with explicit permissions. Built-in WIP limits prevent agents from claiming everything at once.

Framework-agnostic. Lobsidian is a convention layer. It works with any agent that can read and write files.

Human-compatible. Everything is plain markdown. Browse motives in Obsidian. Review decisions in VS Code. Approve tasks in your terminal. The vault works without any agent at all.

Agent Skill

Lobsidian ships an Agent Skill at skills/lobsidian/SKILL.md. Compatible with any platform supporting the Agent Skills standard:

• Claude Code
• OpenAI Codex
• Gemini CLI
• Cursor
• GitHub Copilot
• OpenClaw / ClawHub
• Goose
• Any agent supporting Agent Skills

If your platform doesn't support Agent Skills, load _lobsidian/AGENT.md directly into the agent's context window.

The Protocol

Core Types

| Type | Folder | Purpose | |------|--------|---------| | motive | Motives/ | Why something needs attention (situation + need + effect) | | decision | Decisions/ | What was decided, with success criteria and review date | | task | Tasks/ | Concrete work with assignee, deliverables, and outcome | | note | Knowledge/ | Captured insights and reference material | | log | Journal/ | Chronological entries (daily, activity, meeting, reflection) | | domain | _lobsidian/domains/ | Agent scope, permissions, and boundaries |

Status Flows

Motives: open -> addressed -> obsolete

Decisions: draft -> proposed -> active -> under-review -> retired or superseded

Tasks: pending -> claimed -> in-progress -> done or cancelled

Spec

The full protocol specification is in spec.md (~960 lines). Advanced multi-agent coordination, cascade protocols, and domain emergence are in spec-advanced.md.

The spec was developed through 15 expert agent reviews and 67 fixes across 8 versions. Design history is in CHANGELOG.md.

Contributing

Found a bug or have a suggestion? Open an issue.

License

MIT