Agents forget, and shared context gets messy.
Long-running projects need durable facts, provenance, decisions, and session history. Free-form notes alone are readable, but not easy to validate or coordinate across tools.
Stable v3.0 core + v3.1 agentic hardening
Memory that agents can read, propose, and audit.
Obsidian Memory for AI is a Markdown-first memory protocol: atomic facts, append-only events, generated views, portable linting, and cooperative write envelopes for agents. No database. No daemon. No vector store.
v3 vault shape
Just files
vault/
|-- CLAUDE.md
|-- COPILOT.md
|-- AGENTS.md
|-- sources/
`-- memory/
|-- schema/
|-- facts/
| `-- elena-voss/role.md
|-- events/2026-05-11/
|-- _views/
| |-- by-entity/elena-voss.md
| `-- conflicts.md
|-- _inbox/agent-id/ops/
|-- _claims/
|-- _ops/applied/
`-- _archive/
`-- tools/
|-- lint.py
|-- ops.py
|-- compact.sh
`-- query.sh
Convention is the schema. The filesystem is the index.
v3 keeps the files human-readable while giving agents typed records, stable identities, generated read models, and reviewable writes.
Split human notes from agent records.
Keep narrative pages for humans. Give agents atomic facts, append-only events, schema-checked frontmatter, generated views, and an inbox for proposed writes.
How it works
A memory protocol made of folders, YAML, and small scripts.
v3.0 is the stable Atomic Markdown Memory core. v3.1 adds a cooperative write flow for agentic environments without introducing a database or service.
Human narrative stays human
`memory/people/`, `memory/projects/`, and `memory/context/` remain prose-first Obsidian notes optimized for reading, linking, and thinking.
Facts become atomic
Durable agent-facing facts live one tuple per file under `memory/facts/{entity}/{predicate}.md`, with typed frontmatter and provenance.
Events are append-only
Session-level history goes to `memory/events/YYYY-MM-DD/`, preserving time, source, and derived facts without rewriting old memory.
Views are generated
`_views/` gives agents fast read models by entity, predicate, timeline, stale facts, operations, claims, and conflicts. Regenerate them, never edit them.
v3.1 agentic hardening
Agents propose changes. The compactor applies them.
v3.1 makes cooperation explicit: proposed writes are Markdown operation envelopes, not direct mutations of canonical memory. A human or trusted compactor validates, applies, rebuilds views, and records receipts.
Operation envelopes
Agents write proposed operations to `memory/_inbox/{agent-id}/ops/`, with reason, target, source, payload, and status.
Stable record IDs
Facts and events can carry durable `id:` values, so paths stay readable without being the only identity.
Precondition hashes
Update and archive operations can include a content hash for optimistic conflict detection before a write is applied.
Advisory claims
Cooperative agents can create TTL-based `_claims/` files for a target. They are diagnostic coordination files, not distributed locks.
Applied receipts
Applied operations are preserved under `_ops/applied/`, so the vault keeps an audit trail of who proposed what and what actually changed.
Operational views
Generated views surface inbox state, operations, conflicts, claims, IDs, and predicates so agents can inspect the system before acting.
Reference vault
A complete v3 example, not just a template.
The repository includes a fictional Elena Voss vault with typed facts, events, generated views, operation helpers, linting, compaction, and query scripts.
Elena Voss
v3 reference
examples/v3-minimal-vault/
|-- CLAUDE.md
|-- README.md
|-- sources/
|-- tools/
| |-- lint.py
| |-- ops.py
| |-- compact.sh
| |-- rebuild-views.sh
| `-- query.sh
`-- memory/
|-- entities.md
|-- schema/
|-- facts/elena-voss/
|-- events/2026-05-11/
|-- _views/
|-- _inbox/
|-- _claims/
`-- _ops/applied/# Context for AI sessions
## v3 memory protocol
- Human-readable narrative lives in memory/people/,
memory/projects/, and memory/context/.
- Agent-readable facts live in memory/facts/ and
must pass tools/lint.py.
- New session records live in memory/events/YYYY-MM-DD/.
- Proposed agent writes should be operation envelopes in
memory/_inbox/{agent-id}/ops/.
- Cooperative claims live in memory/_claims/; treat them
as advisory, not transactional locks.
- Read generated context from memory/_views/ when available,
but never edit _views directly.---
type: fact
id: fact-elena-voss-role
entity: elena-voss
predicate: role
value: "Art conservator and pigment researcher"
valid_from: 2025-09-01
valid_to: null
recorded_at: 2026-05-10T22:14:00Z
confidence: high
sources:
- sources/profile.md
last_reviewed: 2026-05-11
decay:
review_after_days: 180
archive_after_valid_to: true
pin: false
------
type: operation
operation_id: op-20260512t180000z-1a2b3c4d
op: create_fact
agent_id: agent-copilot-1a2b3c4d
created_at: 2026-05-12T18:00:00Z
target_id: fact-elena-voss-language
target_path: memory/facts/elena-voss/language.md
precondition_hash: null
status: proposed
reason: "Capture a durable language preference."
sources:
- sources/session-2026-05-12.md
payload:
type: fact
id: fact-elena-voss-language
entity: elena-voss
predicate: language
value: Spanish
---# memory/_views/by-entity/elena-voss.md
Generated by tools/rebuild-views.sh. Do not edit.
## Active facts
- role: Art conservator and pigment researcher
source: memory/facts/elena-voss/role.md
- base: Berlin, Germany
source: memory/facts/elena-voss/base.md
- primary-project: Concordance
source: memory/facts/elena-voss/primary-project.md
## Operations
- pending: 1 proposed operation in _inbox/
- conflicts: noneDesign choices
The tradeoffs are intentional.
Plain text over infrastructure
Your memory is a folder you can read, edit, version, tar, sync, and move. There is no hosted retrieval API deciding what the agent remembers.
Schema without a database
Frontmatter declares types. YAML schemas and `tools/lint.py` enforce required fields, path semantics, dates, predicates, wikilinks, and contradictions.
Bi-temporal by default
Facts distinguish when something is true in the world from when it was recorded, preserving temporal context without a graph engine.
Query with boring tools
Paths, frontmatter, `rg`, `yq`, and `tools/query.sh` cover the personal-context scale this system is designed for.
Git as audit log
Every memory change is visible in diffs and history. Generated views make derived state reviewable instead of hidden in a service.
Additive migration
Existing vaults can adopt v3 gradually: add schemas and tools, write new facts atomically, and backfill durable records as they become useful.
Compatibility
Same memory, different agents.
Claude Code
Reads CLAUDE.md natively and can follow the v3 protocol in the vault.
GitHub Copilot
Use COPILOT.md, repo instructions, and operation envelopes for proposed writes.
Anthropic Memory Tool
Map memory/ to /memories: facts, events, decisions, insights, views, and inbox.
Obsidian Agent Skills
Pair the protocol with Obsidian-aware skills for frontmatter, wikilinks, and vault conventions.
Cursor and others
Adapt the loading mechanism. The data stays as Markdown files in your vault.
Scope
What you get and what you don't.
Included
- Atomic semantic facts with stable IDs and source provenance
- Append-only episodic events for session history
- Generated views for agent reads and operational diagnostics
- Portable lint, query, operation, and compaction scripts
- Cooperative write flow with proposed operations and applied receipts
Not included
- A database, vector store, graph engine, daemon, or hosted memory API
- Transactional guarantees for distributed multi-agent workloads
- Automatic forgetting in the background; decay is a review ritual
- Enterprise-scale retrieval over millions of records
- A black box that decides what you remember
Get started
Clone the reference vault, run the linter, inspect the views.
The stable v3.0 core is ready to use. The v3.1 hardening additions are already in the reference implementation for cooperative agent workflows.
FAQ
Questions
Is this still just Markdown?
Yes. The source of truth is still files in your vault: Markdown, YAML frontmatter, generated Markdown views, and small scripts that travel with the vault.
Is v3.1 a database in disguise?
No. v3.1 adds operation envelopes, advisory claims, precondition hashes, and receipts. Those make cooperative file workflows safer, but they do not add SQL, transactions, embeddings, a daemon, or a remote service.
How do multiple agents write safely?
Agents propose changes under their own inbox folder. The compactor validates the envelope, checks preconditions, applies the change, rebuilds views, and records an applied receipt. Conflicts stay visible instead of being silently merged.
Do I need v3.1 if the stable v3.0 core is enough?
No. v3.1 is additive hardening for cooperative agents. If one human and one agent update the vault manually, the stable v3.0 core can be enough.
Does this only work with Claude?
No. Claude Code has a strong native file convention, but the protocol is tool-neutral. Copilot, Cursor, local agents, and any AI that can read files can use the same vault.
Why not use a vector database or a dedicated memory product?
Different layer. Vector and graph systems are strong for large retrieval problems. This system handles curated personal and project context where transparency, ownership, auditability, and portability matter more than managed infrastructure.