From e967fa874a7915bd4ee608133a7b58578040e8cc Mon Sep 17 00:00:00 2001 From: windyboy Date: Wed, 7 Jan 2026 23:38:29 +0800 Subject: [PATCH] docs: add comprehensive Memvid MCP integration documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Expanded Memory Integration section in project-instructions.md - Added detailed Memvid Workflows section to WORKFLOWS.md - Documented all available Memvid tools and use cases - Added tagging guidelines and best practices - Included complete workflow examples for common scenarios - Integrated Memvid workflows with existing PARA and Git workflows 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .claude/project-instructions.md | 269 +++---- 06_Metadata/WORKFLOWS.md | 1174 +++++++++++++++++++++++++++++++ 2 files changed, 1266 insertions(+), 177 deletions(-) create mode 100644 06_Metadata/WORKFLOWS.md diff --git a/.claude/project-instructions.md b/.claude/project-instructions.md index deae4d8..82bac24 100644 --- a/.claude/project-instructions.md +++ b/.claude/project-instructions.md @@ -1,214 +1,129 @@ -# Obsidian PKM 助理工作指南 +# Obsidian PKM Assistant - - -## Memvid MCP memory rules - -- Use the `memvid` MCP server only for durable preferences, decisions, and long-lived project context. -- At the start of each task, query memory before acting. - - Use `memvid_search` (or `memvid_search_by_tag` when tags are available). -- After each task, write back any new durable preferences/decisions/constraints. - - Use `memvid_add_text` or `memvid_add_file`, then `memvid_commit`. -- Never store secrets, tokens, credentials, or transient errors/logs. -- Use consistent tags like `project`, `decision`, `preference`, `constraint`. -- Default memory file path: `.claude/memory/memvid.mv2` (override only if user specifies). - - -> 本指南叠加在 Claudian 基础能力之上，专注于个人知识管理的内容整理与组织。 +> Core principles only. See `06_Metadata/WORKFLOWS.md` for detailed procedures. --- -## 核心原则 +## Safety First -### 1. 信息安全优先 -- **零丢失承诺**：合并笔记时保留所有原始信息，删除仅限明确重复且可验证等价的内容 -- **变更前审批**：任何涉及移动、重命名、合并、删除的操作，先给出计划（影响面 + 回滚方案） -- **链接完整性**：重构后检查并更新所有相关的双链 `[[]]` 和引用 +### Data Integrity +- **Never delete without approval** - Always ask before removing content +- **Preserve everything when merging** - Only remove verified exact duplicates +- **Verify before moving** - Check destination exists, update all `[[wikilinks]]` after +- **Read before writing** - Use Read tool before editing any file -### 2. 输出可直接使用 -- 使用标准 Markdown 格式 -- 添加 YAML frontmatter（tags、created、modified、status 等） -- 优先使用双链 `[[Note]]` 而非普通链接 -- 避免依赖特定插件功能（除非明确说明可用） - -### 3. 渐进式组织 -- Inbox 是临时空间，内容最终应归档到 PARA 结构 -- 简单任务直接执行，复杂任务先给建议再操作 -- 不确定的信息用 `[待确认]` 标注，并列出需补充的信息清单 +### File Operations +- Use `mv` not `cp` (avoid duplicates) +- Never move numbered folders (00-06) from vault root +- Get approval for bulk operations affecting 5+ files --- -## Vault 结构（PARA 方法） +## PARA Structure ``` -vault/ -├── 00_Inbox/ # 临时捕获点，每周整理 -├── 01_Projects/ # 有明确截止日期的项目 -├── 02_Areas/ # 持续关注的领域 -├── 03_Resources/ # 主题参考资料库 -├── 04_Archive/ # 已完成/不活跃内容 -├── 05_Attachments/ # 图片、PDF 等多媒体 -└── 06_Metadata/ # 文档、模板、计划 +00_Inbox/ → Temporary capture, process weekly +01_Projects/ → Time-bound work with deadlines +02_Areas/ → Ongoing responsibilities +03_Resources/ → Reference materials +04_Archive/ → Completed items +05_Attachments/ → Media files +06_Metadata/ → Docs & templates ``` -**文件夹选择逻辑**： -- **有截止日期？** → 01_Projects/ -- **需持续维护？** → 02_Areas/ -- **纯参考资料？** → 03_Resources/ -- **临时/未决定？** → 00_Inbox/（稍后整理） +**Quick Decision**: Deadline? → Projects | Ongoing? → Areas | Reference? → Resources | Unsure? → Inbox --- -## 工作模式 +## Git Essentials -根据任务类型自动选择合适的处理方式： +```bash +# Always start sessions with +git pull -### 快速整理 -将原始内容结构化为笔记（标题层级、列表、表格、代码块） +# After significant work +git add . && git commit -m "vault backup: $(date)" && git push +``` -### 归档组织 -- 分析内容性质，建议放置路径 -- 给出文件命名建议（遵循现有命名规范） -- 推荐相关标签和 frontmatter 字段 - -### 知识提炼 -- 提取核心结论、洞察、行动项 -- 将证据与观点分离 -- 建立与现有笔记的链接 - -### 检索问答 -- 基于提供的笔记内容回答 -- 引用时注明具体位置（标题、段落） -- 使用引用块 `>` 标注原文 +Commit format: `vault backup: YYYY-MM-DD HH:MM:SS` --- -## 输出规范 +## Memory Integration -### 标准格式 -```markdown +Use Memvid MCP for persistent context across sessions: + +### Core Workflow +1. **Query first**: Always search memory at task start: `memvid_search` +2. **Work**: Complete task using retrieved context +3. **Write back**: Save decisions: `memvid_add_text` + `memvid_commit` + +### What to Store +- **DO**: User preferences, decisions, constraints, patterns, project context +- **DON'T**: Secrets, credentials, errors, logs, temporary data + +### Memory File Location +- Default: `.claude/memory/memvid.mv2` +- Project-specific: `.claude/memory/[project-name].mv2` + +### Tagging Strategy +Use consistent tags for retrieval: +- `type:preference` - User preferences and settings +- `type:decision` - Architectural and design decisions +- `type:constraint` - Project limitations and requirements +- `type:pattern` - Code patterns and conventions +- `project:[name]` - Project-specific context +- `area:[name]` - Area-specific information + +### Quick Reference +``` +Search: memvid_search(query, top_k=5) +Add: memvid_add_text(content, tags={"type": "decision"}) +Commit: memvid_commit() +List: memvid_list_contents(limit=20) +Info: memvid_info() +``` + +See `06_Metadata/WORKFLOWS.md#memvid-workflows` for detailed procedures. + +--- + +## Note Standards + +### Frontmatter +```yaml --- created: YYYY-MM-DD -tags: [tag1, tag2] -status: draft|active|archived +modified: YYYY-MM-DD +tags: [specific, tags] +status: draft|active|complete|archived --- - -## 摘要 -[2-5 句话总结核心内容] - -## 正文 -[使用清晰的标题层级] - -## 相关笔记 -- [[相关笔记1]] -- [[相关笔记2]] - -## 待确认 -- [ ] 需要补充的信息点 ``` -### 变更计划格式 -当需要重构/合并/移动时，提供： +### Linking +- Use `[[wikilinks]]` for internal connections +- Link liberally, prefer over-linking +- Check and update links after reorganizing -```markdown -**变更摘要**：[一句话说明目标] - -**影响文件**： -- 源文件：path/to/old.md -- 目标文件：path/to/new.md -- 受影响链接：约 X 处 - -**具体操作**： -1. 步骤一 -2. 步骤二 - -**回滚方式**： -[如何撤销此变更] -``` +### Organization +- Inbox is temporary - process weekly +- One idea per note (atomic notes) +- Flat structure over deep nesting (max 3 levels) +- Use links not folders for relationships --- -## 重构安全检查清单 +## Work Approach -在执行移动/重命名/合并前，必须确认： +**Simple tasks** → Execute directly +**Complex changes** → Propose plan first (affected files, steps, rollback) +**Uncertain info** → Mark `[待确认]` and ask -- [ ] 是否有其他笔记链接到此文件？ -- [ ] 是否需要添加 alias 保持旧链接可用？ -- [ ] 合并后是否有信息丢失？ -- [ ] 是否需要在原位置留下重定向说明？ +For bulk operations, provide: +- What's changing and why +- Files affected +- Rollback approach --- -## 技术操作规范 - -### 路径使用 -- ✅ 正确：`03_Resources/note.md` -- ❌ 错误：`/03_Resources/note.md`（不要加前导斜杠） - -### Git 工作流 -- 大规模整理后，使用 `git status` 检查变更 -- 完成一组相关操作后，建议执行 commit -- 提供清晰的 commit message - -### 文件操作 -- 移动文件用 `mv`（避免重复） -- 操作前先验证目标路径存在 -- 修改文件前先用 Read 工具读取当前内容 - ---- - -## 常见任务指南 - -### 整理 Inbox -1. 分析每个文件的性质（项目/领域/资源/临时） -2. 给出批量移动建议（按优先级排序） -3. 标注需要合并的重复内容 -4. 建议需要添加的 frontmatter - -### 合并重复笔记 -1. 对比内容，列出差异点 -2. 设计合并后的结构 -3. 说明信息保留策略 -4. 给出新笔记完整内容 - -### 创建知识地图（MOC） -1. 扫描相关主题的所有笔记 -2. 按逻辑关系分组 -3. 生成带分类的双链列表 -4. 添加简短说明文字 - ---- - -## 协作约定 - -### 我会主动 -- 发现笔记中的重复内容时提醒 -- 注意到孤立笔记时建议建立链接 -- 遇到不确定内容时明确标注 - -### 我不会主动 -- 删除任何看似冗余的内容（除非你明确要求） -- 执行大规模重构（除非你确认计划） -- 修改已有笔记的核心观点 - -### 遇到不确定时 -- 提供 2-3 个选项供选择 -- 说明每个选项的优缺点 -- 询问你的偏好而非自行决定 - ---- - -## 快速命令参考 - -| 需求 | 建议说法 | -|------|---------| -| 整理单个笔记 | "整理这篇笔记，建议放置位置和标签" | -| 合并重复内容 | "对比这几篇笔记，给出合并方案" | -| 创建主题地图 | "为 XX 主题创建 MOC" | -| 批量归档 | "整理 Inbox，给出移动计划" | -| 检查链接完整性 | "检查这篇笔记的所有链接是否有效" | - ---- - -_此指南是对 Claudian 基础能力的补充，不替换其技术操作规范。_ -_最后更新：2026-01-05_ +**Detailed workflows, templates, troubleshooting**: → `06_Metadata/WORKFLOWS.md` diff --git a/06_Metadata/WORKFLOWS.md b/06_Metadata/WORKFLOWS.md new file mode 100644 index 0000000..667c2d7 --- /dev/null +++ b/06_Metadata/WORKFLOWS.md @@ -0,0 +1,1174 @@ +# Obsidian Vault Workflows - Detailed Reference + +**Generated**: January 07, 2026 +**Purpose**: Comprehensive guide for vault management +**Organization**: PARA Method +**Status**: Reference Documentation + +> This is a detailed reference. For core rules, see `.claude/project-instructions.md` + +--- + +## Table of Contents + +1. [Output Templates](#output-templates) +2. [PARA Method Explained](#para-method-explained) +3. [Naming Conventions](#naming-conventions) +4. [Inbox Management](#inbox-management) +5. [Attachments Management](#attachments-management) +6. [Web Content Workflow](#web-content-workflow) +7. [Writing Style Guidelines](#writing-style-guidelines) +8. [Git Workflow](#git-workflow) +9. [Daily Workflows](#daily-workflows) +10. [Available Commands](#available-commands) +11. [Best Practices](#best-practices) +12. [Troubleshooting](#troubleshooting) +13. [Memvid Workflows](#memvid-workflows) + +--- + +## Output Templates + +### Standard Note Format + +```markdown +--- +created: YYYY-MM-DD +modified: YYYY-MM-DD +tags: [tag1, tag2, tag3] +status: draft|active|complete|archived +type: note|project|area|resource +--- + +# Title + +## Summary +[2-3 sentence overview] + +## Content +[Main content with clear heading hierarchy] + +## Related Notes +- [[Related Note 1]] +- [[Related Note 2]] + +## References +- [Source 1](URL) +``` + +### Change Plan Template + +Use this when proposing bulk operations (moves, merges, deletions): + +```markdown +**Change Summary**: [One sentence describing the goal] + +**Affected Files**: +- Source: `path/to/source.md` +- Target: `path/to/target.md` +- Links affected: ~X places + +**Steps**: +1. Step one with specific command +2. Step two with verification +3. Step three with link updates + +**Rollback**: +[Exact steps to undo if something goes wrong] + +**Verification**: +- [ ] All files moved successfully +- [ ] Links updated and tested +- [ ] No broken references +``` + +### Working Mode Descriptions + +**Quick Organization**: Structure raw content into readable format (headings, lists, tables, code blocks) + +**Archive & Organize**: Analyze content, suggest PARA placement, recommend tags and frontmatter + +**Knowledge Distillation**: Extract insights, separate evidence from conclusions, establish connections + +**Search & Answer**: Respond based on vault content, cite specific locations, quote sources + +--- + +## PARA Method Explained + +### Projects (01_Projects/) + +**Definition**: Time-bound initiatives with clear completion criteria + +**Characteristics**: +- Has a specific end goal +- Has a deadline or completion state +- Contains discrete tasks and deliverables +- Will eventually move to Archive + +**Examples**: +- Writing a research paper +- Planning a presentation +- Learning a specific skill +- Organizing an event + +**Structure**: +``` +01_Projects/[ProjectName]/ +├── README.md # Project overview, goals, timeline +├── Research/ # Background materials +├── Drafts/ # Work in progress +├── References/ # Supporting documents +└── Output/ # Final deliverables +``` + +### Areas (02_Areas/) + +**Definition**: Ongoing responsibilities without end dates + +**Characteristics**: +- Continuous maintenance required +- Standards to uphold +- No completion date +- Generates multiple projects over time + +**Examples**: +- Health & Fitness +- Professional Development +- Finances +- Relationships +- Home Management + +**Structure**: +``` +02_Areas/[AreaName]/ +├── Overview.md # Area definition and standards +├── Projects.md # Related project links +└── Resources.md # Helpful references +``` + +### Resources (03_Resources/) + +**Definition**: Topics of interest for reference and learning + +**Characteristics**: +- Not tied to current projects +- Reference material +- Long-term knowledge building +- Curated information + +**Examples**: +- Programming languages +- Historical topics +- Philosophical concepts +- Technical documentation +- Book notes + +**Structure**: +``` +03_Resources/[TopicName]/ +├── Index.md # Topic overview +├── Notes/ # Individual concept notes +└── References/ # Source materials +``` + +### Archive (04_Archive/) + +**Definition**: Completed projects and inactive items + +**When to Archive**: +- Projects: When objectives are met +- Areas: When no longer relevant +- Resources: When superseded or outdated + +**Structure**: +``` +04_Archive/ +├── Projects/ # Completed projects +├── Areas/ # Inactive areas +└── Resources/ # Outdated resources +``` + +--- + +## Naming Conventions + +### Daily Notes +``` +YYYY-MM-DD - [Topic or Activity] +Example: 2026-01-05 - Meeting Notes +``` + +### Meeting Notes +``` +Meeting - [Topic] - YYYY-MM-DD +Example: Meeting - Project Planning - 2026-01-05 +``` + +### Ideas +``` +Idea - [Brief Description] +Example: Idea - Automated Daily Review Process +``` + +### Resources +``` +Resource - [Topic] - [Source] +Example: Resource - PARA Method - Forte Labs +``` + +### Clippings (Auto-generated) +``` +[Domain]_[Timestamp].md +Example: anthropic.com_1736095200.md +``` + +### Movement Best Practices + +**ALWAYS**: +- Use `mv` command (not `cp`) to avoid duplicates +- Verify destination folder exists before moving +- Update internal links after moving files +- Add YAML frontmatter when organizing +- Commit changes after significant reorganization + +**NEVER**: +- Move files with number prefixes (00-06) from root +- Delete files without reviewing content +- Create deep folder hierarchies (max 3 levels) +- Leave broken links after reorganization + +--- + +## Inbox Management + +### Core Principles + +- Inbox is **temporary**, not permanent storage +- Process weekly using: Capture → Process → Organize +- Maintain fewer than 20 unprocessed items +- Everything in inbox should be recent (< 1 week old) + +### What Stays in Inbox Permanently + +- Files with number prefixes: `00-`, `01-`, etc. +- Core configuration files +- Active daily notes (last 7 days) +- Current weekly summaries (last 3 months) + +### Processing Workflow + +**Step 1: Review** +```bash +git status # See what's new +ls 00_Inbox/ # List inbox contents +``` + +**Step 2: Decide** + +For each item, ask: +- Is this actionable? → Create task or project +- Is this reference? → Move to Resources +- Is this project-related? → Move to Projects +- Is this outdated? → Delete or archive +- Needs more work? → Tag `#needs-processing` + +**Step 3: Organize** +```bash +# Move to appropriate location +mv "00_Inbox/filename.md" "01_Projects/ProjectName/" + +# Verify +ls "01_Projects/ProjectName/" +``` + +**Step 4: Commit** +```bash +git add . +git commit -m "Organize inbox: processed weekly items" +git push +``` + +### Inbox Clippings Folder + +- Firecrawl automatically saves web content here +- Process within 1 week +- Move to appropriate PARA location +- Delete duplicates or low-value content + +--- + +## Attachments Management + +### Organization Rules + +**Storage Location**: +- All non-text files: `05_Attachments/` +- Unprocessed: `05_Attachments/` +- Processed: `05_Attachments/Organized/` + +**Naming Convention**: +``` +[RelatedNote]_[Description].[ext] + +Examples: +ProjectProposal_Diagram.png +Research_StatisticsTable.pdf +Meeting2026-01-05_Whiteboard.jpg +``` + +**Supported File Types**: +- Images: PNG, JPG, GIF, SVG +- Documents: PDF, DOCX +- Data: CSV, XLSX, JSON +- Media: MP3, MP4 (use sparingly) + +### Processing Workflow + +**Step 1: List Unprocessed** +```bash +ls 05_Attachments/ +``` + +**Step 2: Review Each File** +- Is it referenced in notes? Keep and rename +- Is it orphaned? Delete or add reference +- Is it project-related? Keep with clear name + +**Step 3: Rename and Move** +```bash +mv "05_Attachments/screenshot.png" "05_Attachments/Organized/ProjectName_Feature.png" +``` + +**Step 4: Update Links** +Update any markdown references: +```markdown +Before: ![](../05_Attachments/screenshot.png) +After: ![](../05_Attachments/Organized/ProjectName_Feature.png) +``` + +--- + +## Web Content Workflow + +### Built-in Tools (Preferred Method) + +**WebSearch Tool**: +- Use for: General web searches, current information +- Output: Search results with sources +- Action: Copy relevant content into notes manually + +**WebFetch Tool**: +- Use for: Specific URLs, documentation pages +- Output: Page content in markdown format +- Action: Save to appropriate PARA location + +**Best Practices**: +1. Use WebSearch/WebFetch within Claude Code +2. Review content before saving +3. Add frontmatter and context +4. Save to appropriate folder (not Inbox unless processing later) +5. Include source URL in frontmatter + +### Firecrawl Scripts (Batch Processing) + +**Single URL**: +```bash +pnpm firecrawl:scrape +# Saves to: 00_Inbox/Clippings/ +``` + +**Batch URLs**: +```bash +pnpm firecrawl:batch +# Saves to: 00_Inbox/Clippings/ +``` + +**Auto-generated Frontmatter**: +```yaml +--- +source_url: https://example.com/article +scraped_date: YYYY-MM-DD +tags: [clipping, needs-processing] +--- +``` + +**Processing Clippings**: +1. Review content quality +2. Add relevant tags and notes +3. Move to appropriate PARA location +4. Delete low-value clippings + +--- + +## Writing Style Guidelines + +### Structure Standards + +**Internal Linking**: +- Use `[[WikiLinks]]` for all internal references +- Link liberally (better too many than too few) +- Create bidirectional links when relevant +- Use descriptive link text + +**Markdown Formatting**: +- Headings: Use `#` hierarchy (H1 for title, H2 for sections) +- Lists: Use `-` for unordered, `1.` for ordered +- Code: Use backticks for inline, triple backticks for blocks +- Emphasis: `**bold**` for important, `*italic*` for subtle + +**YAML Frontmatter**: +- Always include: created, modified, tags +- Optional: status, type, project, area +- Keep tags specific and consistent +- Update modified date when editing + +### Content Style Preferences + +**Direct Communication**: +- Lead with the main point +- Avoid unnecessary preambles +- Be specific and concrete +- Use active voice + +**Avoid**: +- Clichéd transitions ("In today's world...") +- Filler phrases ("It's worth noting that...") +- Unnecessary qualifiers ("I think maybe...") +- Overused business jargon + +**Prefer**: +- Clear, confident statements +- Specific examples over generalizations +- Simple sentences over complex +- Technical precision when needed + +--- + +## Git Workflow + +### Critical Rule + +**ALWAYS start sessions with `git pull`** to sync latest changes from remote repository. + +### Daily Workflow + +**Morning (Session Start)**: +```bash +cd D:\tmp\vault\my-vault +git pull +git status # Check for any conflicts +``` + +**During Work**: +```bash +git status # Periodically check changes +``` + +**Evening (Session End)**: +```bash +git status # Review all changes +git add . # Stage all changes +git commit -m "vault backup: $(date +%Y-%m-%d\ %H:%M:%S)" +git push # Sync to remote +``` + +### Commit Message Guidelines + +**Format**: +``` +[type]: [brief description] + +Examples: +vault backup: 2026-01-05 20:30:15 +Add: Project planning notes for Q1 initiatives +Update: Weekly review template with new sections +Organize: Moved inbox items to appropriate folders +Archive: Completed research project +``` + +**When to Commit**: +- After organizing inbox +- After creating new notes +- After significant edits +- Before ending session +- After weekly review + +### Common Git Commands + +```bash +git status # Check current state +git pull # Sync from remote +git add . # Stage all changes +git commit -m "message" # Commit with message +git push # Sync to remote +git log --oneline -10 # View recent commits +``` + +### Handling Conflicts + +If `git pull` shows conflicts: +1. Review conflicted files +2. Resolve conflicts manually +3. Stage resolved files: `git add .` +4. Commit: `git commit -m "Resolve merge conflicts"` +5. Push: `git push` + +--- + +## Daily Workflows + +### Morning Routine (5 minutes) + +```bash +# 1. Sync changes +git pull + +# 2. Check inbox +ls 00_Inbox/ + +# 3. Review today's focus +# Create or open: YYYY-MM-DD - Daily Notes.md +``` + +**Daily Note Template**: +```markdown +--- +created: YYYY-MM-DD +type: daily +tags: [daily, journal] +--- + +# YYYY-MM-DD - Daily Notes + +## Focus for Today +- [ ] Primary task 1 +- [ ] Primary task 2 +- [ ] Primary task 3 + +## Capture +[Quick notes throughout the day] + +## Reflections +[End of day thoughts] +``` + +### Evening Routine (5 minutes) + +```bash +# 1. Process quick inbox items +ls 00_Inbox/ + +# 2. Update project notes +# Review and update active projects + +# 3. Commit changes +git status +git add . +git commit -m "vault backup: $(date)" +git push +``` + +### Weekly Review (30-45 minutes) + +See `WEEKLY_REVIEW.md` for complete checklist. + +**Quick Overview**: +1. Process entire inbox (target: zero items) +2. Review all active projects +3. Update area notes +4. Archive completed items +5. Clean up attachments +6. Plan next week + +--- + +## Available Commands + +### Attachment Management +```bash +pnpm attachments:list # List unprocessed attachments +pnpm attachments:organized # Count organized files +pnpm attachments:orphans # Find unreferenced files +pnpm attachments:update-links # Update links after moving +``` + +### Web Content +```bash +pnpm firecrawl:scrape # Scrape single URL +pnpm firecrawl:batch # Scrape multiple URLs +``` + +### Git Operations +```bash +git pull # Sync from remote +git status # Check modifications +git add . # Stage all changes +git commit -m "message" # Commit with message +git push # Sync to remote +``` + +### Folder Navigation +```bash +cd D:\tmp\vault\my-vault # Vault root +ls 00_Inbox/ # List inbox +ls 01_Projects/ # List projects +find . -type d | sort # Map all folders +``` + +--- + +## Best Practices + +### Organization Principles + +**Keep It Shallow**: +- Maximum 3 levels of folders +- Create subfolders only with 7+ related notes +- Use linking over deep nesting +- Flat is better than nested + +**Maintain Clarity**: +- Include README.md in major folders +- Use consistent naming conventions +- Tag consistently and specifically +- Update frontmatter regularly + +**Regular Maintenance**: +- Weekly inbox processing (non-negotiable) +- Monthly project reviews +- Quarterly archive cleanup +- Daily git commits + +### Content Creation Principles + +**Capture First, Organize Later**: +- Don't let organization block capture +- Inbox is for quick entry +- Process in batches, not individually +- Speed over perfection initially + +**One Idea Per Note**: +- Atomic notes are more reusable +- Easier to link and discover +- Better for future reorganization +- Clear single purpose + +**Link Generously**: +- Create connections between ideas +- Build bidirectional links +- Use consistent link syntax +- Review links when moving files + +**Tag Consistently**: +- Use specific tags over generic +- Maintain tag vocabulary list +- Tag for retrieval, not categorization +- Review tags during weekly review + +### Maintenance Schedule + +**Daily**: +- Morning: `git pull`, check inbox +- Evening: Commit changes, `git push` + +**Weekly**: +- Process entire inbox +- Review active projects +- Update area notes +- Clean attachments folder + +**Monthly**: +- Review all projects for completion +- Archive inactive items +- Consolidate resources +- Update documentation + +**Quarterly**: +- Deep archive review +- Prune old resources +- Update folder structure if needed +- Review and refine workflows + +--- + +## Troubleshooting + +### Common Issues + +**Inbox Overflow**: +- Schedule immediate processing session +- Delete obvious low-value items first +- Process in batches by type +- Set calendar reminder for weekly review + +**Broken Links**: +- Use attachment update script +- Manually verify critical links +- Commit after fixing links +- Document link structure + +**Git Conflicts**: +- Always start with `git pull` +- Resolve conflicts immediately +- Don't force push +- Backup before major changes + +**Lost Files**: +- Check git history: `git log --all --full-history -- ` +- Look in Archive folders +- Search by content: use grep or Obsidian search +- Check recent commits for moves + +--- + +## Templates + +### Project README Template + +```markdown +--- +created: YYYY-MM-DD +status: active +tags: [project] +deadline: YYYY-MM-DD +--- + +# Project Name + +## Goal +[One sentence goal] + +## Context +[Why this project matters] + +## Deliverables +- [ ] Deliverable 1 +- [ ] Deliverable 2 + +## Timeline +- Start: YYYY-MM-DD +- End: YYYY-MM-DD + +## Resources +- [[Related Resource 1]] +- [[Related Resource 2]] + +## Notes +[Project-specific notes] +``` + +### Area Overview Template + +```markdown +--- +created: YYYY-MM-DD +status: active +tags: [area] +type: area +--- + +# Area Name + +## Purpose +[Why this area matters] + +## Standards +[What success looks like] + +## Active Projects +- [[Project 1]] +- [[Project 2]] + +## Resources +- [[Resource 1]] +- [[Resource 2]] + +## Review Schedule +[How often to review this area] +``` + +### Resource Index Template + +```markdown +--- +created: YYYY-MM-DD +tags: [resource, topic-name] +type: resource +--- + +# Topic Name - Index + +## Overview +[Brief introduction to this topic] + +## Key Concepts +- [[Concept 1]] +- [[Concept 2]] +- [[Concept 3]] + +## Related Topics +- [[Related Topic 1]] +- [[Related Topic 2]] + +## Sources +- [Source 1](URL) +- [Source 2](URL) +``` + +--- + +## Memvid Workflows + +### Overview + +Memvid is a semantic memory system that provides persistent context across Claude Code sessions. It uses vector embeddings to enable intelligent search and retrieval of previous decisions, preferences, and project context. + +### Core Concepts + +**Memory File (`.mv2`)**: +- Single portable file containing all data, embeddings, and indices +- Default location: `.claude/memory/memvid.mv2` +- Project-specific files: `.claude/memory/[project-name].mv2` + +**Semantic Search**: +- Uses natural language queries +- Returns contextually relevant results +- No need for exact keyword matching + +**Tagging**: +- Organize content with key-value tags +- Enable fast filtering and categorization +- Combine with semantic search for precision + +### Initial Setup + +**Check Server Status**: +```bash +# Verify Memvid is running +# Check server version and features +``` + +**Create Memory File** (if not exists): +```bash +# Create new memory file at default location +# File: .claude/memory/memvid.mv2 +# Description: Vault management context and preferences +``` + +**Verify Creation**: +```bash +# Check memory file info +# Should show 0 entries initially +``` + +### Daily Workflows + +**1. Session Start - Query Context** + +Start every work session by retrieving relevant context: + +```bash +# Search for general preferences +Query: "user preferences for organizing vault" + +# Search for project-specific context +Query: "decisions about [project-name] structure" + +# Search for recent changes +Query: "recent workflow updates" +``` + +**Best Practice**: Query first, work second. Always check memory before making decisions. + +**2. During Work - Capture Decisions** + +Document important decisions as you work: + +**What to Capture**: +- Architectural decisions ("Why did we structure folders this way?") +- User preferences ("User prefers flat structure over deep nesting") +- Project constraints ("Project deadline: 2026-03-15") +- Code patterns ("Use [[wikilinks]] for all internal references") +- Tool choices ("Use mv not cp to avoid duplicates") + +**Example Captures**: +```markdown +# After organizing files +Content: "User prefers to keep inbox items under 20 files. Process weekly, not daily. Move files using mv command to avoid duplicates." +Tags: {"type": "preference", "topic": "inbox-management"} + +# After making architectural decision +Content: "Decided to use PARA method for vault organization. Projects (time-bound), Areas (ongoing), Resources (reference), Archive (completed). Maximum 3 levels of nesting." +Tags: {"type": "decision", "topic": "structure", "date": "2026-01-07"} + +# After learning constraint +Content: "Never move numbered folders (00-06) from vault root. These are core structure folders and must remain at top level." +Tags: {"type": "constraint", "topic": "folder-structure"} +``` + +**3. After Changes - Commit to Memory** + +Always commit after adding content: +```bash +# Commit changes to persist them +# This ensures data is saved to disk +``` + +**Important**: Uncommitted changes may be lost. Commit after each add or batch of adds. + +### Common Use Cases + +**Use Case 1: Learning User Preferences** + +```bash +# Initial conversation about preferences +User: "I prefer concise writing without filler phrases" + +# Store preference +Add text: "User writing preferences: Direct, concise communication. Avoid clichéd transitions like 'In today's world'. Avoid filler phrases like 'It's worth noting'. Use active voice and specific examples." +Tags: {"type": "preference", "topic": "writing-style"} +Commit: Yes + +# Future sessions - retrieve preference +Search: "user writing preferences" +Result: [Returns stored preference for consistent communication] +``` + +**Use Case 2: Project Context** + +```bash +# Starting new project +Add text: "Project: Weekly Review Automation. Goal: Create automated system to process inbox and generate weekly summaries. Tech stack: Node.js, Obsidian API. Deadline: 2026-02-01." +Tags: {"type": "project", "project": "weekly-review-automation", "status": "active"} +Commit: Yes + +# Mid-project decision +Add text: "Weekly Review Automation: Decided to use Dataview plugin instead of custom scripts. Easier to maintain, better Obsidian integration." +Tags: {"type": "decision", "project": "weekly-review-automation"} +Commit: Yes + +# Later session - retrieve context +Search: "weekly review automation project" +Result: [Returns project goals and decisions] +``` + +**Use Case 3: Troubleshooting Patterns** + +```bash +# After solving a problem +Add text: "Git conflict resolution: When seeing merge conflicts after git pull, resolve manually in affected files, then git add . && git commit -m 'Resolve merge conflicts' && git push. Never force push." +Tags: {"type": "pattern", "topic": "git-workflow"} +Commit: Yes + +# Future similar problem +Search: "how to resolve git conflicts" +Result: [Returns established pattern] +``` + +**Use Case 4: Vault Organization Rules** + +```bash +# Document organizational decision +Add text: "Attachment naming convention: [RelatedNote]_[Description].[ext]. Example: ProjectProposal_Diagram.png. Store in 05_Attachments/Organized/ after processing." +Tags: {"type": "pattern", "topic": "attachments"} +Commit: Yes + +# Later when organizing attachments +Search: "attachment naming convention" +Result: [Returns established pattern] +``` + +### Advanced Features + +**Tag-Based Search**: +```bash +# Find all decisions +Search by tag: key="type", value="decision" + +# Find project-specific items +Search by tag: key="project", value="weekly-review-automation" + +# Find all preferences +Search by tag: key="type", value="preference" +``` + +**Export Search Results**: +```bash +# Export for documentation +Query: "all organizational decisions" +Format: markdown +Top K: 20 + +# Creates formatted markdown with search results +``` + +**List Recent Additions**: +```bash +# View last 20 entries +Limit: 20 + +# Quick overview of recent context +``` + +**Memory Info**: +```bash +# Get memory statistics +# Shows: entries count, file size, creation date, last modified +``` + +### Best Practices + +**DO**: +- ✓ Query memory at start of every session +- ✓ Store decisions immediately after making them +- ✓ Use descriptive tags for easy retrieval +- ✓ Commit after adding content +- ✓ Store "why" not just "what" (reasoning behind decisions) +- ✓ Use natural language in queries +- ✓ Tag with both type and topic +- ✓ Review memory periodically to refresh context + +**DON'T**: +- ✗ Store sensitive data (passwords, API keys, tokens) +- ✗ Store temporary data (errors, logs, debug output) +- ✗ Store file contents (use references instead) +- ✗ Forget to commit changes +- ✗ Use vague tags like "misc" or "other" +- ✗ Store data that changes frequently +- ✗ Duplicate information already in vault files + +### Tagging Guidelines + +**Standard Tag Structure**: +``` +type:[category] - Primary classification +topic:[subject] - Specific subject area +project:[name] - Project association +date:[YYYY-MM-DD] - When decision made +status:[state] - Current state +``` + +**Recommended Tags**: +- `type:preference` - User preferences and settings +- `type:decision` - Architectural and design decisions +- `type:constraint` - Project limitations and requirements +- `type:pattern` - Established patterns and conventions +- `type:context` - Background information and rationale + +- `topic:structure` - Organizational structure decisions +- `topic:workflow` - Process and workflow definitions +- `topic:writing` - Writing style and standards +- `topic:git` - Version control practices +- `topic:attachments` - File management patterns + +### Maintenance + +**Weekly Review**: +```bash +# List recent additions +Limit: 50 + +# Review for: +- Outdated information +- Duplicate entries +- Missing tags +- Unclear descriptions +``` + +**Monthly Cleanup**: +- Search for outdated project references +- Archive completed project context +- Update changed preferences +- Consolidate similar entries + +**Quality Checks**: +- Are tags consistent and descriptive? +- Do searches return relevant results? +- Is context clear without vault access? +- Are decisions documented with reasoning? + +### Troubleshooting + +**Issue: Search returns no results** +- Check memory file exists: `memvid_info` +- Verify content was committed +- Try broader search terms +- Check tag filters + +**Issue: Too many irrelevant results** +- Use more specific queries +- Add tag filters to narrow scope +- Increase specificity in stored content +- Use combined semantic + tag search + +**Issue: Forgetting to use memory** +- Add "check memory" to session start checklist +- Set reminder in daily notes template +- Review recent memory additions weekly + +**Issue: Memory file too large** +- Archive old project-specific memories +- Create separate memory files per major project +- Remove duplicate or outdated entries + +### Examples + +**Complete Session Example**: + +```bash +# === SESSION START === + +# 1. Query for context +Search: "inbox processing preferences" +Result: "User prefers weekly processing, keep under 20 items..." + +Search: "PARA organizational structure" +Result: "PARA method: Projects, Areas, Resources, Archive..." + +# 2. Work on task +# [Process inbox items, move files, organize notes] + +# 3. Document new learnings +Add text: "User prefers to tag web clippings with both 'clipping' and specific topic tags for easier retrieval. Example: tags=[clipping, ai, research]" +Tags: {"type": "preference", "topic": "tagging"} +Commit: Yes + +Add text: "Discovered user has separate organization for daily notes. Keep in 00_Inbox/ for last 7 days, then move to Archive. Format: YYYY-MM-DD.md" +Tags: {"type": "pattern", "topic": "daily-notes"} +Commit: Yes + +# 4. Verify storage +Info: [Shows 2 new entries added] + +# === SESSION END === +``` + +### Integration with Other Workflows + +**With Git Workflow**: +```bash +# Store git conventions +Content: "Git commit message format: 'vault backup: YYYY-MM-DD HH:MM:SS' for routine backups. Use descriptive messages for specific changes." +Tags: {"type": "pattern", "topic": "git"} +``` + +**With PARA Organization**: +```bash +# Store PARA decisions +Content: "Project threshold: Create project folder when 3+ related files exist. Use Projects for time-bound work, Areas for ongoing responsibilities." +Tags: {"type": "decision", "topic": "para-method"} +``` + +**With Daily Notes**: +```bash +# Store daily routine preferences +Content: "Daily notes template: Focus section at top, Capture section for quick notes, Reflections at bottom. Review previous day's notes each morning." +Tags: {"type": "preference", "topic": "daily-workflow"} +``` + +--- + +**Last Updated**: January 07, 2026 +**Maintained By**: Vault Owner +**Version**: 2.0 (Consolidated from CLAUDE.md)