Skip to content

README.md

Latest commit

 

History

History
243 lines (172 loc) · 7.99 KB

README.md

File metadata and controls

243 lines (172 loc) · 7.99 KB
Raw

Synapse

The AI-first PKM framework for Obsidian.

Synapse structures your Obsidian vault so AI assistants can effectively read, understand, and work with your notes. It's the connection point between human knowledge and AI.

Why Synapse?

Most PKM systems are designed for human browsing. Synapse is designed for AI retrieval:

  • Frontmatter-first: Every note has structured metadata that AI can parse instantly
  • Self-contained notes: Each note provides full context without requiring link-following
  • Consistent structure: Predictable patterns enable reliable AI interactions
  • Built-in commands: Claude slash commands for common PKM operations

Quick Start

  1. Clone this repo into your Obsidian vault location:

    git clone https://github.com/julien731/synapse-pkm.git my-vault
cd my-vault

  2. Open in Obsidian: Open the folder as a vault

  3. Run setup: Use Claude Code and run /synapse-setup to personalize the vault

  4. Start using: Create notes, and use /synapse-review to ensure they follow AI-first conventions

Folder Structure

vault/
├── .claude/        # Claude commands and configuration
├── inbox/          # Unprocessed items (captures, imports, quick notes)
├── projects/       # Active project briefs and planning
├── ideas/          # Ideas at various stages of development
├── areas/          # Ongoing areas of responsibility
├── resources/      # Reference material, research, learning notes
├── people/         # Contact notes
├── journal/        # Daily notes, reflections, meetings
├── archive/        # Completed or inactive items
└── templates/      # Note templates

Frontmatter Conventions

All notes use YAML frontmatter with these fields:

Field Required Values Purpose
type Yes daily, meeting, project, idea, resource, area, person, reflection Note classification
status For actionable active, completed, archived, on-hold Current state
summary Yes One sentence AI retrieval optimization
tags Recommended Array of strings Topics and themes
created Yes YYYY-MM-DD When the note was created
related If applicable [[wikilinks]] Connected notes

Example Note

---
type: meeting
created: 2026-01-10
status: active
summary: Quarterly planning meeting with design team discussing 2026 roadmap priorities.
tags:
  - planning
  - design
related:
  - "[[projects/Design System Refresh]]"
---

# Q1 2026 Design Planning

Meeting with the design team to establish priorities for the upcoming quarter...

AI Optimization Principles

These principles make notes more effective for LLM retrieval:

1. Use the summary Field

Add a one-sentence summary in frontmatter for every note. This allows AI to understand a note's purpose without reading the full content.

2. Self-Contained First Paragraph

The first paragraph after frontmatter should provide full context: who, what, why, and how this note relates to others. A note should be understandable without following links.

3. Explicit Over Implicit

State context explicitly rather than relying on folder paths or assumptions:

  • Include full names and roles on first mention
  • Avoid ambiguous pronouns ("it", "they") that lose meaning when chunked
  • Repeat key context rather than assuming link-following

4. Consistent Structure Within Types

Notes of the same type should follow the same section structure. This enables pattern matching across similar notes.

5. Atomic Notes

One concept per file. Smaller, focused notes (300-500 words) retrieve more precisely than large documents where relevant content is buried.

What Hurts LLM Retrieval

Pattern Problem
Tables with merged cells Parsing fails
Images without alt text No semantic content
Heavy abbreviations Context lost when chunked
Ambiguous pronouns Referent unclear in isolation
Links without context AI may not follow links

Ideas Workflow

Ideas are generative notes that need space to incubate before becoming projects or being discarded. Unlike resources (reference material you consume), ideas are things you develop over time.

Lifecycle:

new → developing → decided
Status Meaning
new Just captured, hasn't been reviewed yet
developing Actively thinking about it, adding connections
decided Fate determined (became a project or discarded)

Categories: product, workflow, content, personal

Idea-specific fields:

Field Values
status new, developing, decided
category product, workflow, content, personal
outcome null (undecided), [[projects/...]] (became project), discarded

Weekly Review: Use /synapse-review-ideas to review active ideas and decide their fate.

Synapse Commands

Commands are Claude Code slash commands in .claude/commands/.

/synapse-setup - Initialize Vault

Personalizes the vault through a short interview:

  • Collects your identity (name, role, organization)
  • Asks what you'll use the vault for
  • Updates CLAUDE.md and README.md with your context

/synapse-review - Review Notes

Cleans up manually-created notes to comply with AI-first standards:

  • Adds missing frontmatter (summary, type, status, tags)
  • Generates summaries from content
  • Adds self-contained first paragraphs
/synapse-review                  # Review notes from last 7 days
/synapse-review inbox/           # Review specific folder
/synapse-review --all            # Review entire vault

/synapse-review-ideas - Weekly Idea Review

Review ideas to develop them, promote them to projects, or discard them:

  • Surfaces all ideas with status: new or status: developing
  • For each idea, asks what to do: keep developing, promote to project, discard, or skip
  • When promoting, creates a new project and links it to the original idea
/synapse-review-ideas            # Review all active ideas
/synapse-review-ideas product    # Review only product ideas

/synapse-update - Update Framework

Pull the latest Synapse framework updates:

  • Fetches latest commands and templates
  • Shows changelog with migration instructions
  • Preserves your personal content

/synapse-migrate-notion - Migrate from Notion

Import content from a Notion export:

  • Auto-detects Notion structure
  • Interactive mapping to Synapse folders
  • Converts properties to frontmatter
  • Cleans up Notion artifacts
/synapse-migrate-notion                 # Interactive migration
/synapse-migrate-notion ~/path/export   # Specify export path

/synapse-publish - Publish Framework Changes (Maintainers)

Push framework improvements to the public Synapse repository:

  • Identifies changed framework files
  • Strips user-specific content
  • Creates a pull request for review

/synapse-changelog - Generate Changelog (Maintainers)

Document framework updates with migration instructions:

  • Generates structured changelog entries
  • Prompts for migration instructions on breaking changes
  • Updates CHANGELOG.md

Templates

Template Use case
Daily Note Daily planning and reflection
Meeting Note Client, sales, internal meetings
Project Brief Project planning and scope
Idea Ideas to develop and evaluate
Person Contact reference notes

Updating Synapse

When new versions are released:

/synapse-update                  # Check for and apply updates
/synapse-update --check          # Only check, don't apply

Updates only modify framework sections (marked with <!-- SYNAPSE:FRAMEWORK --> comments). Your personal content is preserved.

Contributing

Improvements to the framework are welcome. See the contribution guidelines.

License

MIT License - see LICENSE for details.