Knowledge Vault — the shared Obsidian AI/ notes

A shared Obsidian vault is the agents' long-term memory: the root causes of fixed bugs and the design decisions behind shipped features, accumulated across sessions and across the whole team.

It is a git repository — Friendly-Technologies/ft-obsidian-knowledgebase — that each developer clones and opens as an Obsidian vault. The git repo is the source of truth; Obsidian is just the viewer/editor on top of a clone. A note written by one developer’s agent and pushed is knowledge every teammate’s agent reads on the next related task.

This is the second, complementary knowledge layer — do not confuse it with the Qdrant Knowledge Base.

Qdrant Knowledge Base Obsidian Knowledge Vault

What it holds

product docs, indexed code, protocol specs, historical bugs

our own accumulated root causes & design decisions, per repo

Access

read-only RAG (semantic_search) — grounding

read and write — the agents author notes

Written by

offline indexers (docs/code/bugs pipelines)

the agents themselves, at the end of a task

Reached via

qdrant-vector-db MCP

mcp-obsidian MCP (+ $FT_VAULT_PATH for git)

Analogy

a library you look things up in

a lab notebook the team writes as it goes

The graph — hubs, notes, and the index

Notes are not loose dots. Every note branches off its repository hub (a Map of Content), the hubs branch off the root _Index, and each hub links sideways to that repo’s curated Wiki/. That connectivity is what makes the vault navigable in Obsidian’s graph view.

Only [[wikilinks]] (in the body) and link fields in frontmatter create graph edges — tags and Dataview results do not. A note without a **Hub:** line is an orphan: unfinished work.

What’s in it — the AI/ layout

Path What it holds

Path	What it holds
`AI/_Index.md` ⭐	The authoritative contract — the vault’s own rules. The `obsidian-knowledge-vault` skill mirrors it; on any conflict `AI/_Index` wins.
`AI/<repo-slug> — Hub.md`	The repository hub (Map of Content) — the root node every note for that repo branches from. Links up to `AI/_Index`, sideways to the repo’s `Wiki/`.
`AI/Bugfixes/`	Root causes of fixed bugs. One note = one bug (not one per incremental change). Named `<repo-slug> - <JIRA-key>`.
`AI/Decisions/`	Accepted architecture/feature decisions. One note = one decision/feature. (`type: feature` for features.)
`AI/_Checkpoints/`	Temporary work notes for in-progress MAJOR/CRITICAL work, so a dropped session resumes instead of restarting. Folded into the permanent note and deleted on completion.
`Wiki/<repo-slug>/`	Curated per-repo docs (architecture, gotchas, conventions). Read freely; the agents modify it only when the user explicitly asks.

AI/_Index.md ⭐

The authoritative contract — the vault’s own rules. The obsidian-knowledge-vault skill mirrors it; on any conflict AI/_Index wins.

AI/<repo-slug> — Hub.md

The repository hub (Map of Content) — the root node every note for that repo branches from. Links up to AI/_Index, sideways to the repo’s Wiki/.

AI/Bugfixes/

Root causes of fixed bugs. One note = one bug (not one per incremental change). Named <repo-slug> - <JIRA-key>.

AI/Decisions/

Accepted architecture/feature decisions. One note = one decision/feature. (type: feature for features.)

AI/_Checkpoints/

Temporary work notes for in-progress MAJOR/CRITICAL work, so a dropped session resumes instead of restarting. Folded into the permanent note and deleted on completion.

Wiki/<repo-slug>/

Curated per-repo docs (architecture, gotchas, conventions). Read freely; the agents modify it only when the user explicitly asks.

When the agents touch it — the lifecycle

The vault is an explicit step of the FT pipelines (ft-fix, ft-developer, bugfix-agent), not an optional afterthought. Two touch points bracket every bugfix / feature / refactor:

Step What happens

Step	What happens
Read at start	Search the vault for the JIRA key / repo slug / module / error text and open `AI/<repo-slug> — Hub`. Hits are input knowledge — a teammate’s agent may have already solved this. Do not rediscover it.
Write at end	On a terminal outcome, persist one note per bug/feature: a bugfix root cause → `AI/Bugfixes/`, a design decision/feature → `AI/Decisions/`. If the note already exists, update it in place (never duplicate; supersede with `status: superseded` + `superseded-by`, never delete).
Commit — the agent owns it	`git -C "$FT_VAULT_PATH" pull --rebase` → `add` only the touched files (never `git add -A` in a shared vault) → `commit` → `push`. On a rebase conflict: stop and report — never force-push, never `--no-verify`.

Read at start

Search the vault for the JIRA key / repo slug / module / error text and open AI/<repo-slug> — Hub. Hits are input knowledge — a teammate’s agent may have already solved this. Do not rediscover it.

Write at end

On a terminal outcome, persist one note per bug/feature: a bugfix root cause → AI/Bugfixes/, a design decision/feature → AI/Decisions/. If the note already exists, update it in place (never duplicate; supersede with status: superseded + superseded-by, never delete).

Commit — the agent owns it

git -C "$FT_VAULT_PATH" pull --rebase → add only the touched files (never git add -A in a shared vault) → commit → push. On a rebase conflict: stop and report — never force-push, never --no-verify.

Never write to the vault secrets, tokens, credentials, or customer/personal data. Notes describe code and root causes, not customer environments — and never a machine-specific vault path.

The note format contract (non-negotiable)

Every AI/ note follows the same shape — enforced by the obsidian-knowledge-vault skill:

English only — frontmatter and prose, every note, no exceptions.
YAML frontmatter — repo (canonical hyphenated slug), type, jira, status, date, up: "[[<repo-slug> — Hub]]", tags.
Clear ## sections, never a flat list of bold bullets. Bugfix → Symptom / Root cause (with a file:line path) / Fix / Notes. Decision → Context / Decision / Alternatives / Consequences.
Hub link, zero orphans — frontmatter up: and a body **Hub:** [[<repo-slug> — Hub]] line (the body wikilink is what creates the graph edge), then list the note in its hub.
Canonical hyphenated repo slug everywhere (files, tags, hub) — never the underscore form.
Hygiene self-check after every edit — no stray files, no broken links, no orphans, no phantom placeholder links.

Templates live in the vault’s templates/ folder (bugfix.md, decision.md, hub.md, checkpoint.md) — excluded from the graph so their placeholder links never become phantom nodes.

How the agents reach it — and how to set it up

Two access routes, neither hardcodes a vault path (the machine’s own config resolves wherever the clone lives):

Route Used for

Route	Used for
`mcp-obsidian` MCP (primary)	HTTP to the local Obsidian REST API — search, read, write notes. Resolves to whatever vault Obsidian has open.
`$FT_VAULT_PATH` (env var)	git commits and a direct-write fallback when Obsidian is closed. Set per machine at install time.

mcp-obsidian MCP (primary)

HTTP to the local Obsidian REST API — search, read, write notes. Resolves to whatever vault Obsidian has open.

$FT_VAULT_PATH (env var)

git commits and a direct-write fallback when Obsidian is closed. Set per machine at install time.

Degrades gracefully: MCP reachable → normal; Obsidian closed but $FT_VAULT_PATH set → write the note directly and commit; neither → the task is not blocked, the agent reports "no knowledge persistence this run" and includes the note body for the user to paste in.

Setup is part of install.sh / install.ps1 — the obsidian plugin, the mcp-obsidian server, $FT_VAULT_PATH, and a gh auth check so the agent’s push works unattended. Step-by-step: Deployment & Usage § Plugins / MCP servers.

Next → Knowledge Base (the read-only Qdrant layer) · Claude Toolkit (who runs whom) · Deployment & Usage (install it).