byterover-notion-sync

name	byterover-notion-sync
description	Advanced memory and knowledge management workflows for Byterover MCP Server. Use when creating implementation reports with timelines, documenting features as PRDs, or syncing project documentation folders with automatic conflict resolution. Extends basic retrieve/store operations with structured workflows for documentation, analysis, and knowledge synthesis.

Byterover Notion Sync

Bidirectional knowledge synchronization between Byterover memories and Notion documentation. Converts agent-readable memories into team-digestible documentation (reports, PRDs, architecture docs) and imports structured Notion content back into searchable memories.

Core Capabilities

This skill provides two primary directions for knowledge flow:

1. Memories → Notion Documentation

Transform Byterover memories into structured, human-readable documentation in Notion:

• Implementation reports with timelines
• Product Requirements Documents (PRDs)
• Feature documentation
• Technical architecture documentation

2. Notion → Byterover Memories

Convert Notion pages into searchable, agent-optimized memories:

• Break down documentation into logical chunks
• Preserve structure and context
• Handle nested pages recursively
• Maintain traceability to source

---

Workflow Decision Tree

When user requests documentation creation, use this decision tree:

Is the user asking to:

1. Create/Generate documentation in Notion FROM memories?
   → Go to: Memories to Notion Workflow

2. Import/Convert Notion pages TO memories?
   → Go to: Notion to Memories Workflow

3. Unclear which direction?
   → Ask: "Would you like to:
      A) Create Notion documentation from your Byterover memories
      B) Import Notion content into Byterover memories"

---

Memories to Notion Workflow

Convert Byterover memories into structured Notion documentation.

Step 1: Understand Request

Extract from user query:

• Topic/task name for memory search
• Timeline (if provided): e.g., "July 10-15" or "last week"
• Desired format: implementation report, PRD, feature docs, architecture docs
• Notion destination (if specified): page URL, database, or workspace-level

If format not specified, use the Format Selection Guide to determine appropriate format based on content characteristics.

Step 2: Retrieve Relevant Memories

Call Byterover:byterover-retrieve-knowledge multiple times (3-5 calls) with variations:

Example for "authentication implementation July 10-15":
- Query 1: "authentication implementation July 2025"
- Query 2: "JWT token user login July"
- Query 3: "authentication security decisions"
- Query 4: "user authentication challenges errors"
- Query 5: "auth deployment July 15"

Important: Aggregate results from multiple queries to get comprehensive context.

Step 3: Select Documentation Format

Based on content analysis and user request, choose format:

Implementation Report → references/implementation-report-format.md

• Use when: Describing completed work with timeline
• Indicators: Past tense, temporal progression, challenges & solutions

PRD → references/prd-format.md

• Use when: Planning features, defining requirements
• Indicators: Future tense, user stories, acceptance criteria

Feature Documentation → references/feature-documentation-format.md

• Use when: Explaining how to use something
• Indicators: Usage instructions, code examples, troubleshooting

Technical Architecture → references/technical-architecture-format.md

• Use when: System design, component interactions
• Indicators: Architecture diagrams, design decisions, infrastructure

See references/format-selection-guide.md for detailed selection criteria.

Step 4: Structure Content

Follow the selected format template:

1. Extract information from aggregated memories
2. Organize chronologically (for reports) or logically (for other formats)
3. Fill template sections with relevant content from memories
4. Add context where memories are sparse
5. Create timeline by identifying temporal markers in memories
6. Note gaps as open questions or areas for clarification

Step 5: Determine Notion Destination

User specified destination:

• Page URL → Use Notion:notion-create-pages with page_id parent
• Database URL → First use Notion:notion-fetch to get data source, then use data_source_id parent
• Teamspace → Use Notion:notion-create-pages with teamspace_id

User did not specify:

• Ask: "Where would you like to save this in Notion?" with options:
  • Create as standalone page (can be organized later)
  • Specify a parent page or database
  • Save to a specific teamspace

Default: Create as standalone workspace-level page if user prefers not to specify.

Step 6: Create Notion Page

Use Notion:notion-create-pages:

{
  "parent": {
    "page_id": "..." // or data_source_id or omit for workspace-level
  },
  "pages": [{
    "properties": {
      "title": "[Document Title]",
      // Add other properties if creating in database
    },
    "content": "[Structured markdown content from template]"
  }]
}

For databases, include appropriate properties based on format:

• Implementation Report: Type, Status, Start Date, End Date, Team, Tags
• PRD: Type, Status, Owner, Priority, Target Release, Tags
• Feature Documentation: Type, Status, Category, Tags, Last Updated
• Technical Architecture: Type, Status, System, Owner, Version

Step 7: Confirm and Provide Link

Return to user:

• Link to created Notion page
• Summary of what was documented
• Note any gaps or areas that need manual review
• Suggest follow-up actions if relevant

Example response:

Created Implementation Report: "User Authentication Implementation"

📄 Notion page: https://notion.so/...

Summary:
- Documented 5-day implementation timeline (July 10-15)
- Captured 3 major technical decisions
- Included challenges and resolutions
- Added 8 code examples from memories

Note: Timeline dates were approximate based on memory context. You may want to verify exact dates.

---

Notion to Memories Workflow

Convert Notion pages into Byterover memories while preserving structure.

Step 1: Understand Request

Extract from user query:

• Notion page URL or search query
• Topic/area (if searching rather than direct URL)
• Scope: single page or include nested pages
• Any special focus areas

Step 2: Locate Notion Content

If user provided URL:

• Use Notion:notion-fetch with the page URL/ID

If user provided topic/search query:

• Use Notion:notion-search to find relevant pages
• Present results to user for confirmation
• Fetch confirmed pages

Step 3: Analyze Page Structure

Review fetched content for:

• Main sections (## headings)
• Nested/child pages ( tags)
• Content types: concepts, procedures, code, decisions, APIs
• Total length and complexity

Step 4: Plan Memory Chunks

Follow references/notion-to-memory-guide.md chunking strategy:

Create separate memories for:

• Each major section with substantial content (>100 words)
• Distinct concepts or topics
• Code examples with explanations
• Procedures or workflows
• Decision records
• API endpoints or methods

Memory size guidelines:

• Ideal: 200-800 words
• Minimum: 100 words (combine smaller sections)
• Maximum: 1500 words (split larger sections)

Step 5: Extract and Format Memories

For each planned chunk:

1. Extract content with surrounding context

2. Format based on content type:

   • Concept/Definition
   • Procedure/How-To
   • Code Example
   • Decision/ADR
   • API/Reference
   • Architectural Component

   See references/notion-to-memory-guide.md for templates.

3. Add metadata:

   **Source**: [Page Title] - [Section Name]
   **Topic**: [Main topic]
   [Content formatted according to type]
   **Notion Source**: [Page URL]
   

4. Store memory using Byterover:byterover-store-knowledge

Step 6: Handle Nested Pages

For each child page found in tags:

1. Fetch child page using Notion:notion-fetch
2. Add parent context to memories from child page
3. Repeat conversion process (Steps 3-5)
4. Create relationship memory linking parent and child topics if needed

Step 7: Verify and Summarize

Quality checks before finalizing:

• All major sections converted to memories
• Code examples are complete and formatted
• Source URLs are included
• Context is preserved
• Memory sizes are reasonable

Return to user:

• Count of memories created
• Summary of topics covered
• Any sections skipped or combined
• Confirmation of nested page processing

Example response:

Converted Notion page to memories: "API Authentication Guide"

✅ Created 8 memories:
   - 1 overview memory
   - 3 procedure memories (getting token, using token, refreshing)
   - 2 code example memories
   - 1 troubleshooting memory
   - 1 API reference memory

Processed 2 nested pages:
   - "JWT Token Implementation"
   - "OAuth2 Integration"

Total: 8 parent page memories + 12 nested page memories = 20 memories

All memories include source URLs for traceability.

---

Best Practices

For Memories → Notion

1. Cast wide net: Use multiple memory queries with variations
2. Aggregate first: Collect all relevant memories before structuring
3. Choose format carefully: Use format selection guide
4. Preserve technical accuracy: Don't paraphrase code or technical terms
5. Note gaps: Mark unclear areas as open questions
6. Add timeline context: Extract dates and temporal markers from memories
7. Link related docs: Cross-reference other relevant Notion pages

For Notion → Memories

1. Chunk logically: Keep related information together
2. Preserve structure: Maintain headings, lists, code formatting
3. Add context: Include source page and section information
4. Handle nesting: Process child pages recursively
5. Don't over-split: Avoid creating too many tiny memories
6. Test retrieval: Consider what queries would find these memories
7. Maintain traceability: Always include source URLs

General Guidelines

1. Bidirectional traceability: Always link between Notion and memories
2. Preserve technical detail: Don't lose code, configurations, or specifics
3. Structure consistently: Use templates for reproducibility
4. Focus on reusability: Format for future discovery and use
5. Handle conflicts: If memory conflicts detected, show resolution URL to user
6. Iterate: Ask for user feedback and refine as needed

---

Common Patterns

Pattern 1: Implementation Post-Mortem

User: "Document the auth implementation from last week"

Workflow:
1. Retrieve memories: "authentication", "auth implementation", "JWT", "user login"
2. Format: Implementation Report with Timeline
3. Structure: Timeline, challenges, solutions, outcomes
4. Create in Notion with properties: Type=Implementation Report, Status=Completed

Pattern 2: Feature Planning

User: "Create PRD for notification system based on our discussions"

Workflow:
1. Retrieve memories: "notification system", "push notifications", "notification requirements"
2. Format: PRD
3. Structure: User stories, requirements, technical approach
4. Create in Notion with properties: Type=PRD, Status=Draft, Priority=P0

Pattern 3: Documentation Import

User: "Import our API docs from Notion into memories"

Workflow:
1. Search Notion: "API documentation"
2. Fetch confirmed page
3. Chunk by endpoint/section
4. Format as API Reference memories
5. Store with source URL and context

Pattern 4: Architecture Documentation

User: "Document our microservices architecture"

Workflow:
1. Retrieve memories: "microservices", "architecture", "service design", "infrastructure"
2. Format: Technical Architecture
3. Structure: Components, interactions, design decisions
4. Create in Notion with diagrams (using mermaid syntax)

---

Troubleshooting

Issue: Insufficient Memories Retrieved

Solution:

• Try broader query terms
• Use multiple variations of query
• Adjust time range if applicable
• Ask user to provide more specific topic details

Issue: Can't Determine Format

Solution:

• Ask user directly: "Would you like this as an implementation report, PRD, feature documentation, or architecture document?"
• If still unclear, default to Implementation Report (most general)

Issue: Timeline Information Missing

Solution:

• Note in document: "Timeline approximate based on memory context"
• Use relative markers: "early phase", "later", "final stages"
• Leave specific dates as [TBD] and note for user to fill in

Issue: Memory Conflicts Detected

Solution:

• CRITICAL: Always display conflict resolution URL to user
• Explain conflict briefly
• Provide link for resolution
• Wait for user to resolve before continuing

Issue: Large Notion Page (>5000 words)

Solution:

• Break into multiple memories strategically
• Use nested sections as natural boundaries
• Create index memory linking to sub-memories
• Process in batches if needed

---

References

All reference materials are available in the references/ directory:

• format-selection-guide.md - Determine which format to use for memory → Notion conversion
• implementation-report-format.md - Template for implementation reports with timelines
• prd-format.md - Template for Product Requirements Documents
• feature-documentation-format.md - Template for feature/API documentation
• technical-architecture-format.md - Template for architecture documentation
• notion-to-memory-guide.md - Comprehensive guide for Notion → Memory conversion

---

Examples

Example 1: Create Implementation Report

User: "Create a report on the payment system implementation we did from Oct 10-15"

Process:

1. Query memories: "payment system implementation October", "payment integration", "payment challenges October"
2. Select format: Implementation Report (completed work with timeline)
3. Structure content with timeline, decisions, challenges, outcomes
4. Create Notion page with properties
5. Return link and summary

Example 2: Create PRD from Memories

User: "Turn our notification system discussions into a PRD"

Process:

1. Query memories: "notification system", "push notifications", "notification requirements", "notification design"
2. Select format: PRD (feature planning)
3. Structure: User stories, requirements, technical approach, success metrics
4. Create in product database with proper properties
5. Return link and note any missing requirement details

Example 3: Import Documentation

User: "Import the authentication guide from Notion into memories"

Process:

1. Search Notion: "authentication guide"
2. Fetch page and analyze structure
3. Plan chunks: overview, procedures (3), code examples (2), troubleshooting
4. Extract and format each chunk with proper memory template
5. Store all memories with source URLs
6. Return summary of memories created

Example 4: Document Architecture

User: "Create architecture doc for our microservices setup"

Process:

1. Query memories: "microservices architecture", "service design", "API gateway", "service communication"
2. Select format: Technical Architecture
3. Structure: Components, interactions, design decisions, infrastructure
4. Add mermaid diagrams for visual representation
5. Create in architecture database
6. Return link with component summary