From 86b06e5b474e80203f88055553053e5a0cd6f9da Mon Sep 17 00:00:00 2001 From: Malin Date: Wed, 12 Aug 2026 18:56:23 +0200 Subject: [PATCH] Add Obsidian vault memory skill --- README.md | 4 + skills/obsidian-vault-memory/SKILL.md | 159 ++++++++++++++++++++++++++ 2 files changed, 163 insertions(+) create mode 100644 skills/obsidian-vault-memory/SKILL.md diff --git a/README.md b/README.md index 0138961..e21c405 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,9 @@ than assuming the delegate can fetch it itself. database shapes through measured, reversible, expand-contract cutovers. - `browser-runtime-verification` -- verify browser-facing changes with real visual, DOM/accessibility, console, network, and performance evidence. +- `obsidian-vault-memory` -- use an Obsidian vault as durable cross-session + memory: low-conflict session capture, canonical-note promotion, provenance + links, queryable Bases, and Syncthing-safe write boundaries. ## Provenance @@ -132,6 +135,7 @@ each skill's frontmatter: evaluated, no skill retained) - [citeworthyio/seo-agent](https://github.com/citeworthyio/seo-agent) (MIT) - [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT) +- [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) (MIT) ## Vetting external skills diff --git a/skills/obsidian-vault-memory/SKILL.md b/skills/obsidian-vault-memory/SKILL.md new file mode 100644 index 0000000..a6cfee5 --- /dev/null +++ b/skills/obsidian-vault-memory/SKILL.md @@ -0,0 +1,159 @@ +--- +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.