synap Assistant

A CLI for externalizing your working memory - capture ideas, projects, features, todos, and questions without the overhead of complex tools.

Why?

Your brain is for having ideas, not holding them. But sticky notes get lost, notepads pile up unread, and tools like Asana are overkill for personal capture.

synap solves this by providing:

• Zero-friction capture - dump thoughts in seconds
• Structured retrieval - find anything with search and filters
• AI-assisted triage - agents help you organize, prioritize, and act

Agent Mindset

When assisting users with their synap entries:

1. Capture first, organize later - Never block on classification during fast capture. Get the thought out, refine later.

2. Proactive triage - Regularly surface raw entries needing processing. Don't let the inbox grow stale.

3. Connect the dots - Link related entries, identify patterns, consolidate ideas into projects.

4. Reduce cognitive load - Present summaries and prioritized lists, not exhaustive dumps.

5. Preserve context - Include enough detail for future recall. A cryptic note is useless later.

6. Respect simplicity - Simple thoughts don't need tags, priorities, and parents. Don't over-engineer.

User Preferences (Memory)

synap stores user data in a configurable data directory (default: ~/.config/synap/).

Data files (syncable):

• entries.json - Active entries
• archive.json - Archived entries
• user-preferences.md - Agent memory / user preferences

Config files (local only):

• config.json - Settings (including dataDir for custom data location)
• deletion-log.json - Audit trail for restore

Custom Data Directory (for sync)

Users can point synap to a custom folder (e.g., a git repo for multi-device sync):

synap config dataDir ~/synap-data
# Or during setup:
synap setup

When custom dataDir is set:

• Data files go to the custom location
• Config stays in ~/.config/synap/
• User can sync data folder via git, Dropbox, iCloud, etc.

Preferences Operations

• Read preferences at the start of a session when present.
• Prefer idempotent updates with synap preferences set --section "Tag Meanings" --entry "#urgent = must do today".
• Remove entries with synap preferences remove --section tags --match "urgent".
• List entries with synap preferences list --section tags --json.
• synap preferences --append "## Section" "..." is still supported for raw appends.
• Avoid overwriting user-written content; prefer section-based updates.

Operating Modes

Detect user intent and respond appropriately:

Volume Modes (Quick vs Deep)

Quick Start

Pre-flight Check

Before operations, verify the tool is ready:

synap --version   # Verify installed
synap stats       # Quick health check

If synap: command not found, the user needs to install: npm install -g synap

Command Reference

Capture Commands

synap add <content>

Quick capture of a thought.

synap add "What if we used a graph database?"
synap add "Need to review the API design" --type todo --priority 1
synap add "Prep for demo" --type todo --due 2025-02-15
synap add "Meeting notes from standup" --type note --tags "meetings,weekly"
synap add --type project --title "Website Redesign" "Complete overhaul of the marketing site..."

Options:

• --type <type>: idea, project, feature, todo, question, reference, note (default: idea)
• --title <title>: Short title (auto-extracted from first line if not provided)
• --priority <1|2|3>: 1=high, 2=medium, 3=low
• --tags <tags>: Comma-separated tags
• --parent <id>: Parent entry ID
• --due <date>: Due date (YYYY-MM-DD, 3d/1w, weekday names: monday/friday, or keywords: today, tomorrow, next monday)
• --json: JSON output

synap todo <content>

Shorthand for adding a todo.

synap todo "Review PR #42"
# Equivalent to: synap add "Review PR #42" --type todo

Options: --priority, --tags, --parent, --due, --json

synap question <content>

Shorthand for adding a question.

synap question "Should we migrate to TypeScript?"
# Equivalent to: synap add "..." --type question

Options: --priority, --tags, --parent, --due, --json

synap log <id> <message>

Add a timestamped log entry under a parent entry.

synap log a1b2c3d4 "Started implementation"
synap log a1b2c3d4 "Completed first draft" --inherit-tags

Options:

• --inherit-tags: Copy tags from parent entry
• --json: JSON output

synap batch-add

Add multiple entries in one operation.

# From file
synap batch-add --file entries.json

# From stdin (pipe)
echo '[{"content":"Task 1","type":"todo"},{"content":"Task 2","type":"todo"}]' | synap batch-add

# Dry run
synap batch-add --file entries.json --dry-run

Input format (JSON array):

[
  {"content": "First entry", "type": "idea"},
  {"content": "Second entry", "type": "todo", "priority": 1, "tags": ["work"]}
]

Options:

• --file <path>: Read from JSON file
• --dry-run: Preview what would be added
• --json: JSON output

Query Commands

synap list

List entries with filtering.

synap list                              # Active + raw (default)
synap list --all                        # All except archived
synap list --type todo                  # Only todos
synap list --status raw                 # Needs triage
synap list --priority 1                 # High priority only
synap list --tags work,urgent           # Has ALL specified tags
synap list --since 7d                   # Created in last 7 days
synap list --overdue                    # Overdue entries
synap list --due-before 7d              # Due in next 7 days
synap list --has-due                    # Entries with due dates
synap list --json                       # JSON output for parsing

Options:

• --type <type>: Filter by entry type
• --status <status>: raw, active, wip, someday, done, archived (default: raw,active)
• --tags <tags>: Comma-separated, AND logic
• --priority <1|2|3>: Filter by priority
• --parent <id>: Children of specific entry
• --orphans: Only entries without parent
• --since <duration>: e.g., 7d, 24h, 2w
• --due-before <date>: Due before date (YYYY-MM-DD or 3d/1w)
• --due-after <date>: Due after date (YYYY-MM-DD or 3d/1w)
• --overdue: Only overdue entries
• --has-due: Only entries with due dates
• --no-due: Only entries without due dates
• --all: All statuses except archived
• --done: Include done entries
• --archived: Show only archived
• --limit <n>: Max entries (default: 50)
• --sort <field>: created, updated, priority, due
• --reverse: Reverse sort order
• --json: JSON output

synap show <id>

Show full entry details.

synap show a1b2c3d4
synap show a1b2c3d4 --with-children
synap show a1b2c3d4 --with-related
synap show a1b2c3d4 --json

synap search <query>

Full-text search across content and titles.

synap search "database"
synap search "meeting" --type note --since 30d
synap search "API" --json

Modify Commands

synap edit <id>

Edit entry content.

synap edit a1b2c3d4                          # Opens $EDITOR
synap edit a1b2c3d4 --content "New text"     # Non-interactive
synap edit a1b2c3d4 --append "Follow-up"     # Add to existing
synap edit a1b2c3d4 --title "New title"

synap set <id>

Update entry metadata.

synap set a1b2c3d4 --type project
synap set a1b2c3d4 --status active
synap set a1b2c3d4 --priority 1
synap set a1b2c3d4 --tags "work,Q1"
synap set a1b2c3d4 --add-tags "important"
synap set a1b2c3d4 --remove-tags "draft"
synap set a1b2c3d4 --clear-priority
synap set a1b2c3d4 --parent b2c3d4e5

synap link <id1> <id2>

Create relationships between entries.

synap link a1b2c3d4 b2c3d4e5                # Add to related
synap link a1b2c3d4 b2c3d4e5 --as-parent    # Set hierarchy
synap link a1b2c3d4 b2c3d4e5 --unlink       # Remove relationship

Bulk Commands

synap done <ids...>

Mark entries as done.

synap done a1b2c3d4
synap done a1b2c3d4 b2c3d4e5 c3d4e5f6       # Multiple
synap done --type todo --tags "sprint-1"     # By filter
synap done --dry-run --type todo             # Preview first

synap start <ids...>

Start working on entries (mark as WIP).

synap start a1b2c3d4                         # Single entry
synap start a1b2c3d4 b2c3d4e5                # Multiple
synap start --type todo --tags urgent        # By filter
synap start --dry-run --type todo            # Preview first

Options:

• -t, --type <type>: Filter by type
• --tags <tags>: Filter by tags
• --dry-run: Show what would be started
• --json: JSON output

synap stop <ids...>

Stop working on entries (remove WIP status).

synap stop a1b2c3d4                          # Single entry
synap stop --all                             # Stop all WIP entries
synap stop --dry-run                         # Preview first

Options:

• --all: Stop all WIP entries
• --dry-run: Show what would be stopped
• --json: JSON output

synap archive <ids...>

Archive entries (hides from default view).

synap archive a1b2c3d4
synap archive --status done --since 30d      # Old completed items
synap archive --dry-run --status done        # Preview

synap delete <ids...>

Delete entries (logged for undo).

synap delete a1b2c3d4
synap delete a1b2c3d4 b2c3d4e5 --confirm
synap delete --status archived --since 90d   # Permanent cleanup
synap delete --dry-run --type reference      # Preview

Safety:

• All deletions logged to enable restore

• 10 entries requires --confirm or --force

• Entries with children require --force

synap restore

Restore deleted entries.

synap restore --last 1                       # Most recent
synap restore --last 5                       # Last 5
synap restore --ids a1b2c3d4,b2c3d4e5        # Specific IDs
synap restore --list                         # Show deletion log

Maintenance Commands

synap stats

Overview statistics.

synap stats
synap stats --json

synap export

Export entries.

synap export                                 # All to stdout
synap export --file backup.json              # To file
synap export --type todo --status active     # Filtered

synap import <file>

Import entries.

synap import backup.json
synap import backup.json --dry-run
synap import backup.json --merge             # Update existing + add new
synap import backup.json --skip-existing     # Only add new

synap config

View or update configuration.

synap config                                 # Show all settings + paths
synap config dataDir                         # Show data directory
synap config --reset                         # Reset to defaults

synap save, synap pull, synap sync

Git sync commands for multi-device workflow.

# Save (commit + push)
synap save                                   # Commit + push with auto timestamp
synap save "message"                         # Commit + push with custom message
synap save -m "message"                      # Same as above
synap save --dry-run                         # Preview changes without committing
synap save --no-push                         # Commit locally, don't push

# Pull
synap pull                                   # Pull latest from remote
synap pull --force                           # Pull even with uncommitted local changes

# Sync (pull + save)
synap sync                                   # Pull then save (full round-trip)
synap sync "end of day"                      # Sync with custom commit message
synap sync --dry-run                         # Preview what would happen
synap sync --no-push                         # Pull and commit, but don't push

Git sync error codes:

Workflow Patterns

Multi-Device Sync Setup

1. Set data directory:

   synap config dataDir ~/synap-data
   

2. Initialize git (one-time):

   cd $(synap config dataDir)
   git init
   git remote add origin git@github.com:user/synap-data.git
   synap save "Initial commit"
   

3. Daily workflow:

   synap pull    # Start of day
   synap save    # End of day
   synap sync    # Or full round-trip
   

4. New device:

   git clone git@github.com:user/synap-data.git ~/synap-data
   synap config dataDir ~/synap-data
   

Daily Review

Run this each morning to get oriented:

1. Health check: synap stats
2. Triage raw entries: synap list --status raw
3. Focus list: synap list --priority 1 --type todo
4. Help user decide what to work on first

Weekly Review

Run this weekly to maintain hygiene:

1. Celebrate: synap list --done --since 7d - show what was accomplished
2. Check stalled: synap list --status active --sort updated - find items not touched
3. Review projects: synap list --type project - are they progressing?
4. Clean up: synap archive --status done --since 7d - archive completed items

Triage Workflow

When user has many raw entries:

1. Fetch: synap list --status raw --json
2. For each entry, determine:
   • Type (idea, todo, project, question, reference, note)
   • Priority (1, 2, 3, or none)
   • Tags (infer from content)
   • Parent (if belongs to existing project/feature)
3. Update: synap set <id> --type todo --priority 1 --tags "work"
4. If entry is actually multiple items, split and re-capture
5. Mark refined: synap set <id> --status active

Capture Mode

When user is dumping thoughts rapidly:

1. Just capture with synap add "..." - don't interrupt for classification
2. Use default type (idea) and status (raw)
3. After the capture session, offer to triage

Smart status defaulting: When capturing with priority set, the CLI auto-promotes to active status (skipping triage). When adding entries with full metadata (priority, tags, due), there's no need to manually set status—the entry is already triaged.

Grouping Detection Pattern

After capture sessions, detect opportunities to group related entries:

Grouping workflow:

1. After capture, analyze recent additions: synap list --since 1h --json
2. Group by common tags or detect semantic similarity
3. If grouping detected, propose: "These 4 entries seem related to [topic]. Create a parent project?"
4. On confirmation:
   • synap add "[Topic] Project" --type project --tags "topic"
   • For each child: synap link <child-id> <project-id> --as-parent

Daily Tracking Pattern

For projects requiring ongoing progress logging (standups, journals, learning logs):

Daily tracking workflow:

1. Setup: Create a project to track

   synap add "Learn Rust" --type project --tags "learning,daily-tracking"
   

2. Daily logging: Add timestamped progress

   synap log <project-id> "Completed chapter 3"
   

3. Review progress: View the log tree

   synap tree <project-id>
   

When to suggest: User creates learning/progress project, mentions accountability, or asks about daily tracking.

Do NOT auto-create - always confirm with user first.

Classification Rules

Type Detection Heuristics

Priority Assignment

Safety Rules

Non-negotiable constraints:

1. Never auto-delete - Always show what will be deleted and confirm
2. Preserve context - Don't summarize away important details during capture
3. Log before delete - All deletions are recoverable via synap restore
4. Confirm bulk operations - Operations affecting >10 entries require confirmation
5. Don't over-organize - Simple thoughts don't need tags, priorities, and parents

Git sync safety:

6. Preview before sync - Use --dry-run to preview changes before committing
7. Handle conflicts carefully - MERGE_CONFLICT errors require manual resolution
8. Protect uncommitted work - pull checks for dirty tree; use --force only when safe
9. Commit messages are safe - Never executed as shell commands (stdin-based commit)

Proactive Recommendation Patterns

• If raw entries are piling up, suggest synap triage.
• If P1 todos exist, suggest synap focus.
• If many stale active items exist, suggest a weekly review.
• If preferences specify cadence, follow it by default.
• If 3+ entries added with common tags/context, suggest grouping under a parent project (see Grouping Detection Pattern).

Batch Processing Protocols

• Filters are for discovery; use IDs for execution.
• Keep batches small (10-25 items) and confirm between batches.
• Use --dry-run whenever available before bulk changes.

Two-Step Pattern for Bulk Operations

Critical for preventing accidental mass changes:

1. Preview: synap delete --status archived --since 90d --dry-run
2. Confirm: Show user what will be affected, get explicit approval
3. Execute: synap delete --ids "<specific-ids>" --confirm

Principle: Filters are for DISCOVERY, IDs are for EXECUTION.

Common Request Patterns

Troubleshooting

Testing / Evaluation Scenarios

JSON Output Schemas

Entry Object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "The full text of the entry",
  "title": "Short title (optional)",
  "type": "idea|project|feature|todo|question|reference|note",
  "status": "raw|active|wip|someday|done|archived",
  "priority": 1|2|3|null,
  "tags": ["tag1", "tag2"],
  "parent": "parent-id|null",
  "related": ["id1", "id2"],
  "due": "2026-01-10T23:59:59.000Z",
  "startedAt": "2026-01-10T08:30:00.000Z",
  "createdAt": "2026-01-05T08:30:00.000Z",
  "updatedAt": "2026-01-05T08:30:00.000Z",
  "source": "cli|agent|import"
}

List Response

{
  "success": true,
  "entries": [...],
  "total": 47,
  "returned": 12,
  "query": {
    "status": ["raw", "active"],
    "limit": 50
  }
}

Error Response

{
  "success": false,
  "error": "Entry not found: a1b2c3d4",
  "code": "ENTRY_NOT_FOUND"
}

Remember

• The goal is to externalize working memory, not build a perfect system
• Capture is king - never block a capture
• Structure serves retrieval, not organizational perfection
• The best system is one that gets used