Skip to content

Instantly share code, notes, and snippets.

@totocaster

totocaster/CLAUDE.md Secret

Created November 5, 2025 06:36
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save totocaster/cc197014af915ec06cb746bab34dbe26 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save totocaster/cc197014af915ec06cb746bab34dbe26 to your computer and use it in GitHub Desktop.
Download ZIP
Instructions for my personal Obsidian/Plaintext Commons note vault
Raw
CLAUDE.md

CLAUDE.md - AI Agent Operating Manual for Toto's Vault

QUICK REFERENCE CARD

# MOST COMMON OPERATIONS
stamp fleeting                                # DEFAULT for ALL new info: 2025-11-12-F143000
stamp daily                                   # ONLY for diary/journal: 2025-11-12
stamp project --check                         # ALWAYS check before creating project
arrowhead search fts "keyword"                # Fast keyword search (~50-100ms)
arrowhead search hybrid "concept"             # Comprehensive search (~400ms)
arrowhead graph backlinks "Note"              # Find incoming links (~25ms)
things-cli anytime                            # View main task list

Golden Rules:

  1. NEVER manually construct date-based filenames
  2. Use stamp fleeting for ALL new info (daily is ONLY for diary)
  3. Prefer appending to existing notes
  4. Use [[wikilinks]] for people
  5. Check before creating (search first, create last)

This manual provides operational instructions for AI agents working with this Obsidian vault. The vault is a flat-hierarchy knowledge management system implementing [[P0450 Plaintext Commons]] - an experimental file-native thinking system with plain Markdown files as source of truth, Arrowhead indexing, and AI-assisted editing.

🚨 CRITICAL OPERATIONAL RULES

1. ALWAYS Use Stamp CLI for Filenames

NEVER manually construct date-based or sequential filenames. The stamp tool is the ONLY authoritative source.

# Information capture (use these for ALL new info)
stamp fleeting                      # → 2025-11-12-F143000 (DEFAULT for all new info)
stamp voice                         # → 2025-11-12-VT143000 (voice transcripts)
stamp analog                        # → 2025-11-12-A1 (paper note photos)

# Journal entry (ONLY for personal diary)
stamp daily                         # → 2025-11-12 (diary/journal ONLY)

# Project operations
stamp project --check               # Check next number FIRST
stamp project "Title"               # → P0455 Title

# Review operations
stamp monthly                       # → 2025-11
stamp yearly                        # → 2025

2. Core Operational Principles

  1. Flat hierarchy mandatory - All notes in root (except Attachments/ and Leaves/)
  2. Never duplicate information - Link to existing notes instead
  3. Prefer appending to existing notes over creating new ones
  4. Use [[wikilinks]] for people and internal references only
  5. No manual date construction - Always use stamp CLI
  6. Frontmatter always comes first - YAML frontmatter must be at the very beginning of the file, followed by the H1 header

PRIMARY WORKFLOWS

1. Processing Notes (/note slash command workflow)

  1. Check existing notes with Arrowhead CLI before creating new ones
  2. Use stamp fleeting for new information capture (NOT daily - that's for diary only)
  3. Append to existing project notes when appropriate

2. Search and Discovery (Arrowhead CLI workflow)

Decision tree:
├─ Know exact keywords? → arrowhead search fts (fastest ~50-100ms)
├─ Exploring concepts? → arrowhead search semantic (~400ms)
├─ Need both? → arrowhead search hybrid (~400ms)
└─ Need connections? → arrowhead graph context, graph backlinks (~25ms)

3. Synthesizing New Notes (combination workflow)

  1. Search existing content with Arrowhead CLI
  2. Read specific notes with Read tool
  3. Check connections with arrowhead graph context "Note"
  4. Use stamp CLI for new filename if needed
  5. Prefer Edit/append over Write for existing notes

TOOL SELECTION MATRIX

Arrowhead CLI Tools

Command Use Case Speed Output Formats
arrowhead search fts "query" Known keywords, titles, metadata filters ⚡ ~50-100ms human, ids, paths, json
arrowhead search semantic "concept" Conceptual exploration, theme discovery 🚀 ~400ms human, ids, paths, json
arrowhead search hybrid "topic" Comprehensive search when uncertain 🚀 ~400ms human, ids, paths, json
arrowhead graph backlinks "Note" Find notes linking TO target ⚡ ~25ms human, json
arrowhead graph forward-links "Note" Find outgoing links from note ⚡ ~10ms human, json
arrowhead graph context "Note" Full graph view (backlinks + forward links) ⚡ ~35ms human, json
arrowhead graph orphans Find notes with no links ⚡ ~11ms human, json
arrowhead graph unresolved Find broken WikiLinks ⚡ ~12ms human, json
arrowhead notes read "Note ID" Get full content after search ⚡ Instant -
arrowhead notes list List all notes in vault ⚡ Fast human, json

Format Options:

  • --format human (default): Multi-column, readable output with scores and previews
  • --format ids: Note IDs only, one per line (perfect for piping)
  • --format paths: Absolute file paths, one per line (for xargs workflows)
  • --json: Machine-readable JSON with full metadata

Direct File Tools

Tool Use Case When to Use
Read Read known files You have exact path
Edit Modify existing content After Read, precise changes
Write Create new files Only when truly new
Bash Run stamp CLI Filename generation

External Integration Tools

Tool Use Case Details
things-cli Task management View/filter todos (read-only)
open "things:///add..." Create tasks URL scheme for task creation
mcp__iMPC__* Calendar/contacts Meeting scheduling, people info

NOTE CATEGORIES & NAMING

Category Quick Reference

CRITICAL DISTINCTION:

  • Fleeting notes = ALL new information capture (meetings, ideas, processing, research)
  • Daily notes = STRICTLY personal diary/journal entries only
Category Purpose Stamp Command Example
fleeting DEFAULT for all new info stamp fleeting 2025-11-12-F143000
journal Personal diary ONLY stamp daily 2025-11-12
project Project documentation stamp project "Title" P0455 Title
evergreen Refined permanent notes Manual naming File over app
person People profiles Manual naming Lorenzo Cipriani
literature Source material (verbatim) Manual naming The Creative Act

Special Naming Patterns (Manual Only)

  • S#### Title - Photo collections (e.g., S0282 Out of Memory Vol 1)
  • JN### Title - Jinny Street Gallery exhibitions (e.g., JN001 Tokyo Flaneur)

Literature Note Rule

CRITICAL: Literature notes must be verbatim copies. Never edit source content.

File Structure Format

CRITICAL: All markdown files must follow this exact structure:

---
category: project/literature/evergreen/etc
status: active/completed/archive
created: YYYY-MM-DD
[additional fields as needed]
---

# Title of Note

Content begins here...

WRONG (H1 before frontmatter):

# My Note Title

---
category: project
---

CORRECT (Frontmatter first):

---
category: project
---

# My Note Title

STAMP CLI OPERATIONS

Counter Management

stamp project --check          # ALWAYS check before creating project
stamp analog --check           # Check today's analog counter
stamp project --counter        # View current project counter (454)
stamp analog --counter         # View today's analog counter
stamp project --set 500        # Correct counter if needed

Configuration: Tokyo timezone, Project counter at P0454, Analog resets daily

DETAILED TOOL DOCUMENTATION

iMPC Tools (Calendar & Contacts)

Calendars: Toto + Ludo (shared), Toto (Private), Landscape, Birthdays, Japan Holidays, F1

Calendar Operations:

mcp__iMPC__calendars_list      # List all calendars
mcp__iMPC__events_fetch        # Get events with filtering
mcp__iMPC__events_create       # Create new events

Contact Operations:

mcp__iMPC__contacts_me         # Your personal info
mcp__iMPC__contacts_search     # Find by name/phone/email
mcp__iMPC__contacts_create     # Add new contacts

Meeting Notes Workflow:

  1. events_fetch → Get meeting details
  2. contacts_search → Find attendee info
  3. stamp fleeting → Create timestamped note for meeting
  4. Add notes with [[person wikilinks]]
  5. Create follow-ups in Things (not iMPC)

Event Prefix Convention: T: (Toto), L: (Ludo), Jinny: (Gallery)

Things CLI (Task Management)

Key Commands:

things-cli anytime              # PRIMARY: Main working list
things-cli today                # HIGH PRIORITY: Today's urgent items
things-cli inbox                # New tasks to triage
things-cli upcoming             # Future scheduled
things-cli search "query"       # Search tasks
things-cli --filter-project "Name" todos   # Filter by project
things-cli --json anytime | jq  # Parse as JSON

Creating Tasks (URL Scheme - always to inbox):

open "things:///add?title=Task%20name"
open "things:///add?title=Task&notes=Context%20info"
open "things:///add?title=Task&when=today"

Task Title Format: Project: specific task (e.g., Synapse: fix search bug)

WORKFLOW: Check anytime (primary) and today (priority) lists

GIT COMMIT FORMAT

YYYY-MM-DD: Brief description

• First change
• Second change
• Additional changes

Example: 2025-09-22: Daily notes and project updates

COMMON TASK PATTERNS

Meeting Notes

  1. stamp fleeting → Get timestamped filename for new info
  2. Create note with [[person wikilinks]]
  3. Create follow-up tasks: open "things:///add?title=Follow%20up%20with%20Person"

Project Work

  1. stamp project --check → Verify next number
  2. Search existing: arrowhead search fts "project term" --limit 10
  3. Append to existing P#### or create new with stamp project "Title"

Voice/Analog Processing

  1. stamp voice or stamp analog → Get filename
  2. Clean up transcription while preserving thought flow
  3. Add [[wikilinks]] to related notes

Research & Synthesis

  1. arrowhead search hybrid "topic" --limit 20 → Comprehensive search
  2. arrowhead graph context "Note" → Find connections
  3. Append to existing evergreen or create new descriptive-named note

ARROWHEAD CLI REFERENCE

Quick Command Reference

# Search commands (all support --limit, --format, --json)
arrowhead search fts "keyword"              # Full-text search (~50-100ms)
arrowhead search semantic "concept"         # Semantic vector search (~400ms)
arrowhead search hybrid "query"             # Combined FTS + semantic (~400ms)

# Graph commands (all support --json)
arrowhead graph backlinks "Note Title"      # Incoming links (~25ms)
arrowhead graph forward-links "Note"        # Outgoing links (~10ms)
arrowhead graph context "Note"              # Full graph view (~35ms)
arrowhead graph orphans                     # Notes with no links (~11ms)
arrowhead graph unresolved                  # Broken WikiLinks (~12ms)

# Note operations
arrowhead notes read "Note ID"              # Read note content
arrowhead notes list                        # List all notes
arrowhead notes list --ids-only             # Just note IDs

# Daemon management
arrowhead status                            # Live daemon status
arrowhead vault start                       # Start daemon
arrowhead vault stop                        # Stop daemon

Search Metadata Filters

FTS search supports field:value syntax:

arrowhead search fts "category:project"           # All project notes
arrowhead search fts "status:active"              # Notes with status:active
arrowhead search fts "tag:photography"            # Tagged notes
arrowhead search fts "photography category:project"  # Combined filters

Output Format Examples

# Human-readable (default)
arrowhead search fts "Arrowhead" --limit 3
# → Shows: title, score, BM25 rank, preview, match reason

# IDs only (for piping)
arrowhead search fts "category:project" --format ids
# → One note ID per line: P0461 Arrowhead CLI

# Paths only (for file operations)
arrowhead search semantic "photography" --format paths
# → Absolute paths: /Users/toto/Notes/totocaster/2025-02-10.md

# JSON (for parsing)
arrowhead search hybrid "query" --json | jq '.[] | .title'
# → Full metadata with scores, wikilinks, tags

Piping Workflows

# Count matches
arrowhead search fts "photography" --format ids | wc -l

# Filter results
arrowhead search fts "P04" --format ids | grep "^P045"

# Process each match
arrowhead search semantic "review needed" --format paths | \
  while read -r path; do open "$path"; done

# Find orphans from 2020
arrowhead graph orphans --json | \
  jq -r '.orphan_notes[] | select(startswith("2020"))'

# Batch tag operation (conceptual)
arrowhead search fts "category:fleeting" --format ids | \
  head -10 > notes-to-process.txt

Performance Notes

  • FTS: ~50-100ms (instant feel)
  • Semantic: ~400ms (sub-second)
  • Hybrid: ~400ms (combines both)
  • Graph ops: ~10-35ms (instant)
  • Daemon: Auto-indexes on file changes
  • Index: 1,534 notes indexed with 0 errors

Match Explanations

Arrowhead shows why each result matched:

P0461 Arrowhead CLI  0.927  -18.80  P0461 Arrowhead CLI
  Reason: Hybrid match (FTS 1.00, semantic 0.45)

Knowledge Management  0.441  N/A  -
  Reason: Semantic similarity 0.44

Declutering Camera Equipment  1.000  -6.19
  Reason: Full-text match (rank -6.19)
  • Hybrid: Shows both FTS and semantic scores
  • Semantic: Shows similarity score (N/A for BM25)
  • FTS: Shows BM25 rank (negative = better)

REFERENCE INFORMATION

Vault Structure

/totocaster/
├── *.md           # All notes (flat hierarchy)
├── Attachments/   # Media files
├── Leaves/       # Analog note photos
└── .obsidian/     # Config

Key Projects

  • [[P0450 Plaintext Commons]] - File-native thinking system being developed
  • [[P0461 Arrowhead CLI]] - Fast Rust-based search/indexing CLI (production-ready)
  • [[P0371 Project Humane Notebook System]] - Analog-digital notebook system
  • [[Jinny Street Gallery]] - Art gallery operations
  • [[The System]] - Core methodology documentation

Context

  • Owner: Toto Tvalavadze (see [[Toto Tvalavadze]] for full details)
  • Company: SSKK (Simulacra and Simulation KK)
  • Location: Tokyo (timezone for all timestamps)
  • Languages: English primary, Georgian/Japanese acceptable
  • Spelling: American English preferred

Important Links

  • [[The System]] - Core principles
  • [[PHNS Workflow]] - Analog-digital bridge
  • [[Values of The System Notetaking]] - Philosophy

Note Evolution

Fleeting → Processing → Evergreen

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment