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

---
name: obsidian-vault-memory
description: 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.
license: MIT
source: 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:

```yaml
---
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:

```yaml
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:

```bash
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.