Symlinked Project Docs: Obsidian as Single Source of Truth for Agent Context

Summary

Keep all project documentation in a single Obsidian vault, then symlink specific subfolders into each git repository. Agents working in a repo get project-specific docs without duplication. Edit in one place, every repo stays current.

The Problem

Project knowledge lives in two places: your notes (Obsidian, Notion, etc.) and your git repos. Copying docs into repos means drift. Keeping them only in notes means agents can’t see them when working on code. You end up manually syncing or missing context entirely.

The Solution

Use your Obsidian vault as the single source of truth. Symlink each project’s doc folder into its corresponding git repo.

Directory Structure

knowledge-base/06-Projects/
├── octospark/            # Real files live here (Obsidian)
├── link-building/        # Real files live here (Obsidian)
├── ai-rank-tracker/      # Real files live here (Obsidian)
└── ...

octospark-services/
└── docs/
    └── knowledge -> ~/Desktop/knowledge-base/06-Projects/octospark  (symlink)

link-building-repo/
└── docs/
    └── knowledge -> ~/Desktop/knowledge-base/06-Projects/link-building  (symlink)

Setup

# Create the symlink (target first, link second)
ln -s ~/Desktop/knowledge-base/06-Projects/octospark ~/path/to/repo/docs/knowledge

Commit the Symlink

Git stores the symlink as a small file containing the target path. Commit it so the link persists across pulls.

git add docs/knowledge
git commit -m "Add symlink to knowledge-base docs"

Note: the absolute path only resolves on your machine. For solo projects this is fine.

Why This Works

1. Single source of truth: edit in Obsidian, agents see it immediately
2. No sync step: symlinks are live file pointers, reads and writes pass through
3. Project-scoped context: each repo only pulls in its relevant docs, agents don’t drown in unrelated material
4. Zero maintenance: no scripts, no CI, no copy jobs
5. Bidirectional editing: changes through the symlink update the real file in Obsidian

Key Properties

• Deleting the symlink does not affect the real files
• Deleting the real files breaks the symlink
• Moving the real files breaks the symlink
• The symlink is a redirect, not a copy

Scaling the Pattern

Every new project gets:

1. A folder in knowledge-base/06-Projects/<project-name>/
2. A symlink from the repo: ln -s ~/Desktop/knowledge-base/06-Projects/<project-name> <repo>/docs/knowledge

Agents working in any repo automatically have access to the right docs.

Related

• symlinked-agent-configs – Same symlink pattern applied to agent configuration files
• hierarchical-context-patterns – Structuring context for agents
• progressive-disclosure-context – Giving agents the right amount of context