/obsidian-memory

name: obsidian-memory
description: |
  Cross-project long-term memory over an Obsidian brain vault: recall relevant
  notes before a task, and persist distilled conclusions (decisions, pitfalls, solutions,
  progress) back after a task. The vault is an optional aggregation/projection layer —
  repo-local artifacts stay the per-project source of truth, and sync direction is
  repo → brain. Explicitly invoked by the model or operator; never executed from hooks.
  Use when the user asks to recall project memory, persist lessons to Obsidian, initialize
  a project sub-vault, or when closing a significant task whose conclusions are worth keeping.
  Triggers: 检索记忆, 查一下知识库, 沉淀经验, 记到 Obsidian, 更新知识库, 复盘沉淀,
  初始化记忆库, recall project memory, persist lessons, update the brain vault,
  knowledge base brain. Do not use for repo-runtime contracts (tasks/, docs/ stay
  authoritative in-repo), raw conversation archiving, or storing secrets.

obsidian-memory — cross-project long-term memory (Obsidian brain vault)

Outcome Contract

• Outcome: recall relevant background from the vault before a task; after the task, persist the conclusions that will still be useful later into the matching project sub-vault, and keep the index current.
• Done when: the recalled notes have been folded into the current context as leads (after re-verification against current state), or the added/updated notes are on disk and the sub-vault `index.md` is in sync.
• Authority model (inviolable): the in-repo artifacts (`tasks/`, `docs/`, `MEMORY.md`, the code) are each project's source of truth; the vault is only a cross-project aggregation/projection layer, and the direction is always **repo → brain**. When the vault conflicts with current state, current state wins, and the vault gets corrected on the spot.
• Two readers: the vault is read by agents **and by the user**. A note must be prose a person can read and learn from directly — complete sentences that state the why and the tradeoff, not agent shorthand and not piles of raw logs; `index.md` is the human reading entrypoint.
• Boundary: this skill may only be invoked explicitly by the model or the user. Hooks never execute it — the hook layer may at most emit a `[BrainPromote]`-style advisory string, and never reads or writes vault state.

Vault resolution (fail-closed, and the vault itself is optional)

1. Read `brainRoot` from `~/.repo-harness/config.json`. 2. Not configured, or the path does not exist → **stop and say so**. Do not scan the disk to guess a vault, and do not create a vault root on the fly. 3. The project sub-vault is `<brainRoot>/<project-slug>/`; `<project-slug>` is the repo directory name or a name the user gives.

**Having no brainRoot configured is a legitimate steady state, not a defect awaiting repair.** Unconfigured simply means this machine does not use the vault layer: the in-repo artifacts remain a complete, authoritative memory surface, and at closeout the conclusions go into the existing slots such as `tasks/lessons.md` and `docs/researches/`. Do not create a vault just so this skill can run. Only when the user explicitly wants the vault layer enabled, point them at `repo-harness install --brain-root <path>` or `repo-harness update --brain-root <path>`.

Phase init · create the project sub-vault

Run this only when the sub-vault does not exist or the user explicitly asks:

1. Create `<brainRoot>/<project-slug>/` containing `index.md` plus, as needed, `decisions/`, `patterns/`, `notes/`, `references/`, `runbooks/` (align with the vault's existing categories; do not invent a new taxonomy). 2. `index.md` records a one-line project background, long-lived preferences, a pointer to current progress, and links to each subdirectory; wiki-link it into the vault root `index.md`. 3. **Hard dependency on the official Obsidian skills**: any action that creates or modifies a `.md` file inside the vault must also invoke the official `obsidian-markdown` skill (the authority for frontmatter, wiki-links, callouts, and other formatting); use the official `obsidian-cli` skill for search, open, and task operations against a running vault. This skill only owns judgment and indexing (what to write, when to write it, how to organize it); it does not define a Markdown dialect of its own. If either official skill is missing, report fail-closed instead of degrading to hand-written formatting.

Phase recall · before the task

1. Read the sub-vault `index.md` first, then `rg` that sub-vault by task keywords (widening to adjacent domains when necessary), and read the full text of at most the 3 most relevant notes. 2. Treat everything recalled as a **lead to re-verify**, never as fact: memory touching files, commands, or versions must be checked against current state before it is used. 3. Sub-vault does not exist → report that there is no memory to recall and ask whether to init; do not skip silently and do not fabricate background.

Phase persist · after the task

1. Extract candidates: key decisions and their reasons, pitfalls with root cause and fix, reusable approaches and patterns, rejected approaches and why they were rejected, progress milestones. 2. **Exclusion-first write gate (apply this one first)** — any fact already recorded authoritatively by git, a package registry, a code-hosting platform, CI, or any re-runnable command gets only a pointer in the vault, never a restatement. That explicitly excludes: commit SHAs, PR/issue numbers, merge commits, CI run ids, tags, release URLs, sync states such as `main == origin/main == <sha>`, whether a worktree is clean, test pass counts, and the snapshot output of a given command run. These start rotting the moment they are written down, and they already have an authoritative source. 3. **Value gate** — after passing the exclusion rule, an entry must also satisfy all of: it will be used again (either for agent reuse or for the user's own learning is enough); it is not a restatement of something a repo a