Docs

Obsidian

Agenties can use an Obsidian vault as the human-readable memory layer for a project. Agents can write research, decisions, session summaries, and handoff notes into Markdown files that you can read directly in Obsidian.

Role in Agenties memory

LayerWhat belongs there
.agenties/Operational truth: issues, goals, agents, sessions, mailbox, shared state, audit logs, and continuity files. Always present.
Obsidian vaultOptional readable layer: decisions, research, summaries, product doctrine, client notes, and project context. Active only when configured.
NotebookLMOptional semantic recall over selected summaries and research material when the Python CLI is installed.
Note:Obsidian is an optional layer. When it is not configured, Agenties uses the local continuity journal and index in .agenties/continuity/ as the session memory source — which is the default for most projects. Obsidian does not replace .agenties/; it complements it with human-readable notes.

When Obsidian is used

Vault tools and session memory are only active when the project config has sessionMemoryProvider set to "obsidian". Configure this in Settings → Integrations → Obsidian. Without it, session init and wrapup read from and write to local .agenties/ files only.

Config valueSession memory source
(not set — default)Continuity journal + index in .agenties/continuity/.
"obsidian"Vault notes matching the project query, plus the continuity journal.

Setup

Configure Obsidian from Settings → Integrations → Obsidian. Set the absolute vault path and enable the integration for the project. Agenties stores notes relative to the vault root and prevents paths outside the vault root for safety.

Recommended layout
<your-vault>/
  <project-name>/
    index.md
    decisions/
    doctrine/
    goals/
    sessions/
    reports/

MCP tools

Four vault tools are exposed to the orchestrator and agents. They are only usable when a vault path is configured for the project. The vault search used during session init is internal — it is not a separate MCP tool.

ToolParametersDescription
read_vault_notenotePathRead a Markdown note from the active project vault.
write_vault_notenotePath, contentWrite or overwrite a Markdown note, creating parent folders if needed.
append_vault_notenotePath, contentAppend content to a Markdown note, creating it if it does not exist.
list_vault_notesfolder?List Markdown files in the vault or in a subfolder.
Tip:All vault paths must be relative to the vault root. Absolute paths and traversal (../) are blocked at the tool level.

Session flow

MomentWhat happens
Session initAgenties searches the vault for notes matching the project name and injects up to 5 excerpts into the startup context alongside the continuity journal.
During workAgents can save research, decisions, and reports into project notes using write_vault_note or append_vault_note.
WrapupA session summary can be exported into the vault so the next session starts with durable context.
Manual inspectionOpen Obsidian directly — notes are plain Markdown files in the vault folder.
Note:Vault search is keyword-based (regex scoring by match density). It is not a semantic/embeddings search. Notes with the highest match density for the project query are selected first.
Tip:Good vault notes are indexes, decisions, and summaries with links back to exact files. Raw logs and large operational dumps should stay in .agenties/.