claude-configs/skills/notediscovery/SKILL.md

name	description
notediscovery	Personal knowledge base management - search, read, create, update, and organize notes in NoteDiscovery. USE WHEN user mentions "note", "notes", "remember this", "save this", "knowledge base", "write down", "jot down", "search my notes", "create note", "update note", or wants to preserve learnings from a session.

NoteDiscovery - Personal Knowledge Base

When to Activate This Skill

Explicit triggers:

• "Add a note about..."
• "Save this to my notes"
• "Search my notes for..."
• "Update my note on..."
• "What do my notes say about..."
• "Remember this for later"
• "Create a note"
• "Delete the note..."

Implicit triggers:

• End of productive session: "Should I save key learnings to your notes?"
• After troubleshooting: "Want me to document this solution?"
• Research findings: "Should I add this to your knowledge base?"

Quick Reference

API Endpoint

• Base URL: https://notes.manticorum.com
• Auth: Password-based session (see client.py)

Core Operations

Operation	Endpoint	Method
Search	/api/search?q={query}	GET
List all	/api/notes	GET
Read note	/api/notes/{path}	GET
Create/Update	/api/notes/{path}	POST
Delete	/api/notes/{path}	DELETE
List tags	/api/tags	GET
Notes by tag	/api/tags/{tag}	GET
Relationship graph	/api/graph	GET

Python Client Usage

from client import NoteDiscoveryClient

# Initialize (reads credentials from environment)
client = NoteDiscoveryClient()

# Search
results = client.search("tdarr troubleshooting")

# Read a note
content = client.read_note("homelab/tdarr-notes")

# Create or update a note
client.save_note("homelab/tdarr-notes", "# Tdarr Notes\n\nContent here...")

# List all notes
notes = client.list_notes()

# Get notes by tag
tagged = client.get_notes_by_tag("homelab")

Workflow Patterns

1. Save Session Learnings

When: End of productive troubleshooting or development session

Pattern:

1. Summarize key learnings from session
2. Search for existing related notes
3. If exists: Read, append new learnings, update
4. If new: Create with proper folder structure and tags

Example prompt handling:

User: "Save what we learned about Tdarr GPU scheduling to my notes"

1. Search for existing: client.search("tdarr gpu scheduling")
2. If found, read and append
3. If not found, create new note:
   - Path: "homelab/tdarr-gpu-scheduling"
   - Content: Structured markdown with tags

2. Quick Capture

When: User wants to quickly save something without structure

Pattern:

1. Create note in inbox/ folder with timestamp
2. Tag with #inbox for later processing
3. Suggest organizing later

Example:

from datetime import datetime
timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
client.save_note(f"inbox/{timestamp}-quick-note", content)

3. Research Integration

When: After research agents return findings

Pattern:

1. Format research results as markdown
2. Add source links and dates
3. Save to appropriate topic folder
4. Tag with #research and topic tags

4. Update Existing Note

When: Adding to or modifying existing knowledge

Pattern:

1. Read existing note
2. Parse current content
3. Add new section or update existing
4. Preserve existing tags, add new if relevant
5. Save updated content

Note Structure Best Practices

Folder Organization

inbox/          # Quick captures, to be organized
homelab/        # Home infrastructure (Tdarr, Docker, VMs, etc.)
development/    # Programming notes and patterns
projects/       # Project-specific notes
  paper-dynasty/
  major-domo/
reference/      # Long-term reference material
journal/        # Time-based entries

Note Format

---
tags:
  - tag1
  - tag2
  - tag3
---

# Title

## Summary
Brief overview

## Details
Main content...

## Related
- [[other-note]]
- [[another-note]]

---
*Last updated: YYYY-MM-DD*

IMPORTANT: Tags MUST use YAML frontmatter format at the top of the note. Do NOT use inline #hashtag format - it won't be indexed properly.

Tagging Convention

• homelab - Infrastructure related
• python - Python development
• troubleshooting - Problem/solution pairs
• reference - Long-term reference
• inbox - Needs organization
• project-name - Project-specific

Smart Behaviors

Auto-Folder Inference

Based on conversation context, infer appropriate folder:

• Talking about Tdarr/Docker/VMs → homelab/
• Python code discussion → development/python/
• Paper Dynasty → projects/paper-dynasty/

Auto-Tagging

Extract relevant tags from content:

• Technology mentions → #tdarr, #docker, #python
• Problem/solution format → #troubleshooting
• Code snippets → #code

Duplicate Prevention

Before creating, search for similar notes:

• If 80%+ title match exists, offer to update instead
• Show existing note summary before proceeding

Environment Variables

Required in environment or .env:

NOTEDISCOVERY_URL="https://notes.manticorum.com"
NOTEDISCOVERY_PASSWORD="your-password-here"

Error Handling

Error	Action
401 Unauthorized	Re-authenticate, retry once
404 Not Found	Note doesn't exist (create vs read context)
500 Server Error	Report to user, suggest retry
Connection Error	Check if notes.manticorum.com is accessible

Proactive Usage

This skill should be offered proactively when:

1. Session ending with valuable learnings
2. Problem solved that wasn't documented
3. Research completed worth preserving
4. Configuration discovered that should be recorded
5. User mentions "I always forget..." or "I should remember..."

Proactive prompt example:

"We discovered some useful patterns for [topic] today. Would you like me to save these to your knowledge base?"

---

Location: ~/.claude/skills/notediscovery/ Client: ~/.claude/skills/notediscovery/client.py Version: 1.0.0 Created: 2024-12-05