agent-skills/skills/obsidian-vault-memory/SKILL.md

name, description, license, source

name	description	license	source
obsidian-vault-memory	Use when an Obsidian vault is the durable memory shared by people, agents, sessions, or devices. Captures session evidence without sync-heavy rewrites, promotes stable knowledge into canonical notes, links provenance, and maintains queryable Obsidian Bases without turning generated views into a second source of truth.	MIT	adapted from https://github.com/kepano/obsidian-skills (MIT), with an original Syncthing-safe memory workflow

Obsidian Vault Memory

Treat the vault as a durable knowledge system, not a transcript dump. Capture what happened append-only, then promote only reusable facts and decisions into stable canonical notes. Markdown remains the source of truth; Bases, backlinks, and search are projections over it.

Discover the vault contract first

Before writing, inspect the vault's existing folders, templates, property names, date format, link style, and attachment location. Reuse them. Do not introduce a parallel taxonomy because a generic template looks cleaner.

Identify four roles, whether or not they are separate folders:

• session notes: chronological evidence and handoff context;
• canonical notes: the current durable understanding of a topic, system, person, project, or decision;
• inbox notes: material not yet classified or verified;
• indexes: .base files or maps of content, never duplicated note content.

If no convention exists, propose one and obtain agreement before migrating or bulk-writing. A safe minimal shape is Sessions/, Knowledge/, Inbox/, and Indexes/.

Use stable properties as the schema

Keep frontmatter small and typed consistently. Start with fields that support an actual retrieval or maintenance need:

---
type: session
created: 2026-08-12
updated: 2026-08-12
status: complete
topics:
  - "[[Obsidian memory]]"
source_session: local-agent-session-id
---

• Use ISO dates so lexical order is chronological.
• Use YAML lists consistently for multi-value properties.
• Quote wikilinks in properties: related: "[[Canonical Note]]".
• Give stable concepts aliases when people may search for another name.
• Do not encode every relationship twice as both a tag and a property. Use tags for broad classification and wikilinks for named relationships.
• Add a property only when a Base, search, template, or maintenance rule consumes it.

Capture a session without rewriting shared hot files

Create one uniquely named session note, for example Sessions/2026-08-12T1430-agent-topic.md. Record:

1. the goal and relevant starting context;
2. evidence observed, with links to source notes or external sources;
3. decisions made and their rationale;
4. changes performed and verification results;
5. unresolved questions and the next concrete action;
6. links to each canonical note created or updated.

Prefer creating a new session note over appending to one global log. On a vault synced by Syncthing or another file-level synchronizer, simultaneous edits to the same Markdown file create conflict copies; unique per-session files reduce the collision surface. Do not treat sync completion as transactional locking.

Before editing an existing note, re-read it immediately before the write. Make a small section-level patch and preserve unrelated human or agent changes. After the write, check for sync-conflict files and report them; never silently choose a winner or delete a conflict copy.

Promote durable knowledge deliberately

At session end, review observations using this test:

• Is it expected to matter in a later session?
• Is it verified, or clearly labelled as an inference/open question?
• Does a canonical note already own this subject?
• Can it replace stale text instead of being appended as another contradictory fact?

Update the owning canonical note with the smallest self-contained fact or decision. Link back to the session note under a Sources or History section so provenance survives compaction. If ownership is unclear, leave the item in the session or inbox instead of creating a near-duplicate canonical note.

Keep history in session notes and current truth in canonical notes. Do not repeatedly paste full session summaries into both places. When new evidence supersedes a fact, update the canonical statement and preserve the old state through the linked session history or an explicit decision record.

Make memory retrievable with Bases

Use an Obsidian Base when the user needs a live index. A Base selects notes through their paths and properties; it does not store a second copy of them. For example:

filters:
  and:
    - 'file.inFolder("Sessions")'
    - 'type == "session"'
views:
  - type: table
    name: "Recent sessions"
    limit: 30
    order:
      - file.name
      - status
      - topics
      - file.mtime

Validate the .base file as YAML, confirm every referenced property exists in the chosen schema, and open it in Obsidian when runtime access is available. Embed a Base in a dashboard with ![[Indexes/Sessions.base#Recent sessions]]; do not hand-maintain the same list in the dashboard body.

Retrieve context before acting

Use the strongest available interface in this order:

1. search properties, names, aliases, and links using Obsidian search or the Obsidian CLI when a running instance is available;
2. inspect the relevant Base and backlinks for related notes;
3. fall back to filesystem search for plain Markdown access.

With the CLI, explicitly target the vault when more than one may be open:

obsidian vault="Vault Name" search query="topic" limit=20
obsidian vault="Vault Name" backlinks file="Canonical Note"
obsidian vault="Vault Name" read path="Knowledge/Canonical Note.md"

The CLI requires Obsidian to be open. Filesystem reads and writes do not, but they cannot prove that Bases, embeds, or links render correctly in the application.

Verify the memory handoff

Before finishing:

• parse changed frontmatter and .base files as YAML;
• confirm new wikilinks resolve or are intentionally future links;
• search for accidental duplicate canonical titles or aliases;
• confirm the session note links to promoted knowledge and vice versa;
• inspect *sync-conflict* files (or the vault's synchronizer convention);
• if Obsidian is available, open the changed notes and Bases and verify rendering;
• report what was captured, what was promoted, what remains uncertain, and whether application-level rendering was tested.

Never claim that a filesystem-valid note is verified in Obsidian unless it was actually opened there.