Turn Obsidian + Claude Code into a Cross‑Project Knowledge Engine

Obsidian + Claude Code: automated cross‑project knowledge reuse

1. Knowledge‑management challenges

When developers work on several projects, solutions and decisions made in one project are often forgotten in another because each project's memory is isolated. Claude Code stores memory per‑project in a .claude/ directory, so knowledge does not flow across projects.

2. Architecture overview

Obsidian – long‑term vault for decisions, experience and reusable knowledge.

PM workspace – a command‑line hub that lists all active projects, their paths and status.

.claude/ – per‑project folder that holds project‑specific memory, rules and skills.

3. Obsidian as a second brain

Folder layout (PARA method)

SecondBrain/
├── 00-控制台/            # Projects (PARA Projects)
│   └── 🎯 项目中心.md   # global project dashboard
├── 01-项目索引/          # project cards
├── 02-领域/              # Areas
├── 03-资源/              # Resources
├── 10-知识库/            # topic‑based notes
│   ├── Claude Code/
│   ├── AI 工具/
│   └── 前端开发/
└── 99-归档/              # Archives

The file 00-控制台/🎯 项目中心.md records status, progress and key decisions for every project, giving a global view inside Obsidian.

4. PM workspace – multi‑project coordinator

Projects are registered with a simple list (example):

微信公众号 – ~/Claude Code/微信公众号 – 🟢 ongoing

Flashlight – ~/Documents/trae_projects/flashlight-new – 🟢 ongoing

保险计划书 – ~/Claude Code/保险/insurance-proposal – 🟢 ongoing

个人网站 – ~/Documents/trae_projects/personal-website – 🟡 maintenance

Key commands (implemented as shell aliases or scripts):

# Switch to a project
pm-goto wechat      # 微信公众号
pm-goto web         # 个人网站
pm-goto insurance   # 保险计划书

# Show status of all projects
pm-status

# Generate a daily report and sync it to the Obsidian vault
pm-report

5. Claude Code – project‑level memory

Each project contains a .claude/ directory with the following structure:

.claude/
├── CLAUDE.md          # project configuration
├── rules/             # specification files
├── memory/            # project memory
│   ├── decisions.md  # important decisions
│   ├── history.md    # chronological history
│   └── lessons.md    # lessons learned
└── skills/            # reusable skills

These files are isolated per project, preventing accidental cross‑project leakage.

6. Integrated workflow

Step‑by‑step process

Record a decision in the Obsidian vault using a standard template.

Run pm-report – it collects the status of every registered project, creates a daily report and writes the report into the vault.

Copy the new decision, history entry and lesson into the corresponding .claude/memory/ files of all affected projects.

When a project is opened, Claude Code automatically reads the updated .claude/ files, making the knowledge instantly available.

Concrete example

## 2026-03-25 - 项目结构优化

**决策**: 采用统一的项目结构规范 CLAUDE.md + rules/memory/skills
**原因**:
- 多项目结构不一致，切换成本高
- 缺少项目记忆，历史决策容易丢失

# Generate report and sync
pm-report
# The command updates decisions.md, history.md and lessons.md in each project's .claude/memory/ folder.

7. Advanced tips

Automated sync

The pm-report command performs three actions:

Collect project status.

Generate a daily report.

Synchronise the report into the Obsidian vault.

Bidirectional links in Obsidian

今天优化了 [[微信公众号]] 的结构。

相关项目：
- [[Flashlight]]
- [[保险计划书]]
- [[个人网站]]

Decision‑record template

## 项目决策模板

**日期**: 2026-03-25
**项目**: 微信公众号
**决策**: 采用 XXX 方案
**原因**: ...
**影响**: ...

8. Pitfalls & mitigations

Avoid over‑recording : only capture decisions that are truly reusable; excess noise reduces Claude Code's retrieval efficiency.

Sync failures : if pm-report stops working, verify the paths of the underlying Python or shell scripts.

Bidirectional‑link abuse : too many links clutter the graph; link only relevant nodes.

9. Ongoing maintenance

Monthly review

Inspect project cards in the Obsidian vault.

Update project statuses.

Archive completed projects.

Extract reusable experience into the knowledge base.

Quarterly cleanup

Delete outdated notes.

Merge duplicate entries.

Refresh project links.

Organise tags and categories.

10. Getting started

Step 1 – Install Obsidian

# macOS
brew install --cask obsidian
# Or download from https://obsidian.md/download

Step 2 – Create the vault

mkdir -p ~/Documents/SecondBrain
# Open Obsidian and select this folder as the vault.

Step 3 – Add a global project dashboard

Create 00-控制台/🎯 项目中心.md and list each project with its status, path and current task.

Step 4 – Initialise project memory

mkdir -p .claude/memory
touch .claude/memory/decisions.md
touch .claude/memory/history.md
touch .claude/memory/lessons.md

Step 5 – Use the system

# Open a project directory
cd ~/your-project
# Launch Claude Code (it will read .claude/ automatically)
claude
# Record decisions; they will be saved in .claude/memory/ and can be synced via pm-report.

11. Conclusion

The three‑layer architecture—Obsidian for long‑term storage, a PM workspace for multi‑project coordination, and .claude/ for project‑level memory—prevents knowledge loss when switching projects, ensures persistence over time, and enables cross‑project reuse. By following the steps above, developers can turn scattered notes into a coherent, growing knowledge asset.