ThinkBank Documentation

Complete command reference for CLI, Claude Chat, and WebUI

Overview

ThinkBank is an AI-powered knowledge management system that captures, evaluates, stores, and reuses valuable insights from your work. This documentation covers all commands and features across three usage modes.

💡 What is ThinkBank?

ThinkBank automatically captures high-value knowledge from conversations, evaluates their long-term worth, organizes them into a searchable database, and reapplies them when relevant. Think of it as "git for thinking" - version control for your intellectual assets.

Quick Start

Installation

# Install from PyPI pip install thinkbank # Verify installation thinkbank --version # Output: ThinkBank 0.1.0a1

First Steps

# 1. Start the web interface thinkbank hub # 2. Check server status thinkbank status # 3. List knowledge items (will be empty initially) thinkbank list
📚 Next Steps

Import sample knowledge or create your own .md files in ~/.thinkbank/knowledge/ to get started. See the File Structure section for details.

Usage Modes

ThinkBank supports three ways to interact with your knowledge base:

🖥️ CLI (Terminal)

Direct command-line access for scripting and automation. Fast and efficient.

💬 Claude Chat

Natural language interface via /thinkbank command. AI-assisted knowledge management.

🌐 WebUI

Visual interface at localhost:8765. Best for browsing and exploration.

When to Use Each Mode

Task Recommended Mode Reason
Browse and explore knowledge WebUI Visual interface, rich formatting
Quick search or list CLI Fastest, scriptable
AI-assisted capture Claude Chat Natural language, context-aware
Import/export packs CLI or Claude Chat Batch operations, automation
Edit knowledge items WebUI Rich editor, preview
🌐

hub

Start the ThinkBank web interface for visual knowledge management.

CLI Usage

# Start on default port (8765) thinkbank hub # Start on custom port thinkbank hub --port 9000 # Start without opening browser thinkbank hub --no-browser

Parameters

Parameter Type Default Description
--port integer 8765 Port number for web server
--no-browser flag false Don't automatically open browser

Claude Chat Usage

# Start web UI /thinkbank hub # Start on custom port /thinkbank hub --port 9000
💡 Claude Integration

When using Claude Chat, the command output is displayed directly in the conversation. Claude can also help you navigate the web interface and interpret results.

WebUI Access

Once the hub is running, access the web interface at:

http://localhost:8765

Interface Preview

📚 Browse View
Search knowledge...
All Types
Skills
Rules
Patterns
SKILL
FastAPI Performance Optimization
Score: 0.87 Tags: python, api, performance
RULE
RESTful API Design Principles
Score: 0.92 Tags: api, design, best-practices
PATTERN
Repository Pattern in Python
Score: 0.85 Tags: python, design-pattern

Features

  • Browse all knowledge items with visual cards showing type, title, score, and tags
  • Search with instant results as you type in the search bar
  • Filter by type, tags, and score using quick filter buttons
  • View full markdown rendering by clicking any knowledge card
  • Edit knowledge items inline with live preview
  • Export/import knowledge packs through visual interface
  • Visualize knowledge relationships with interactive graphs
✨ Pro Tip

The web interface is ideal for exploring your knowledge base visually. Click on any knowledge card to see full details with syntax highlighting and markdown rendering.

📝 Design Updates

Note: These UI previews should be updated whenever the actual WebUI design changes to maintain consistency. The mockup components are located in the CSS section marked "WebUI Mockup Components".

🛑

stop

Stop the ThinkBank web server gracefully.

CLI Usage

thinkbank stop

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ ThinkBank server stopped Server was running on http://localhost:8765 PID: 12345 Uptime: 2h 34m ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Chat Usage

/thinkbank stop
📊

status

Check if ThinkBank server is running and display detailed status.

CLI Usage

thinkbank status

Example Output (Running)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 ThinkBank Server Status Status: Running ✓ URL: http://localhost:8765 PID: 12345 Uptime: 2h 34m Knowledge Base: Total Items: 127 Last Updated: 2 minutes ago ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Example Output (Not Running)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 ThinkBank Server Status Status: Not Running ✗ To start: thinkbank hub ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Chat Usage

/thinkbank status
📚

list

Display knowledge items with optional filtering by type, tags, and quality score.

CLI Usage

# List all items (default: 20) thinkbank list # Filter by knowledge type thinkbank list --type skill # Filter by minimum quality score thinkbank list --min-score 0.8 # Filter by tags thinkbank list --tags "python,api" # Combine filters and limit results thinkbank list --type skill --min-score 0.8 --tags python --limit 10

Parameters

Parameter Type Default Description
--type string all Filter by type: skill, rule, pattern, domain, user, lesson
--min-score float 0.0 Minimum quality score (0.0-1.0)
--tags string none Comma-separated tags to filter
--limit integer 20 Maximum number of items to display

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📚 Knowledge Items (3 found) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SKILL: FastAPI Performance Optimization ID: skill_fastapi_001 Score: 0.87 Tags: python, api, performance SKILL: React Hooks Patterns ID: skill_react_hooks_001 Score: 0.92 Tags: react, frontend, javascript RULE: RESTful API Design Principles ID: rule_rest_design_001 Score: 0.88 Tags: api, design, best-practices ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Chat Usage

# List all items /thinkbank list # Filter by type and score /thinkbank list --type skill --min-score 0.8 # Natural language also works Show me all Python skills with high scores
🤖 AI-Assisted Filtering

When using Claude Chat, you can use natural language to describe what you want to see. Claude will translate your request into the appropriate filters.

WebUI Access

In the web interface, navigate to Browse section to see all knowledge items.

Interface Preview

🔖 Filtered List View (Skills Only)
All Types
Skills
Rules
Patterns
Min Score: 0.8
SKILL
React Hooks Patterns
Score: 0.92 Tags: react, frontend, javascript
SKILL
FastAPI Performance Optimization
Score: 0.87 Tags: python, api, performance
SKILL
Database Indexing Strategies
Score: 0.84 Tags: database, sql, optimization

Features

  • Visual Cards: Each item displayed as a card with type badge, title, score, and tags
  • Live Search: Search bar filters results instantly as you type
  • Type Filter: Quick filter buttons to show only specific knowledge types
  • Score Filter: Slider to adjust minimum score threshold (0.0-1.0)
  • Tag Cloud: Click any tag to filter by topic across all items
  • Sorting: Sort by score (descending), creation date, or title (A-Z)
🧠

collect

v0.2.0

Interactively collect valuable knowledge from current context with AI assistance.

CLI Usage

# Analyze current conversation thinkbank collect # Set minimum score threshold thinkbank collect --threshold 0.7 # Auto-save high-confidence items (≥0.85) thinkbank collect --auto-save # Analyze different scopes thinkbank collect --scope files thinkbank collect --scope clipboard

Parameters

Parameter Type Required Description
--scope choice No conversation, files, clipboard (default: conversation)
--threshold float No Minimum score threshold 0.0-1.0 (default: 0.6)
--auto-save flag No Auto-save items with score ≥ 0.85

How It Works

The collect command provides a user-controlled, interactive way to capture knowledge:

  1. Analyze Context: AI analyzes your conversation/files/clipboard for valuable patterns
  2. Present Menu: Shows a multi-select checklist of detected knowledge
  3. Interactive Selection: Use keyboard shortcuts to select/edit items
  4. Review & Save: Preview and confirm before saving to knowledge base

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🧠 ThinkBank Interactive Collection ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Analyzing current conversation... Threshold: 0.6 Auto-save: No ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📝 Detected Knowledge (3 found) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [✓] 1. SKILL: Shell Tab Completion Score: 0.88 | Tags: cli, shell Context: lines 15-45 [ ] 2. LESSON: PyPI Metadata Issue Score: 0.75 | Tags: python, packaging Context: lines 50-62 [✓] 3. PATTERN: Progressive Refinement Score: 0.92 | Tags: optimization, ai Context: lines 80-120 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⌨️ Controls: Space - Toggle selection a - Select all n - Select none e - Edit selected Enter - Save (2 items) q - Quit ✓ Saved 2 knowledge items to ThinkBank
💡 When to Use

Use collect when you've had a productive conversation and want to actively review what's worth saving. Perfect for capturing multiple related insights at once.

Claude Chat Usage

# Trigger collection /thinkbank collect # Natural language Collect knowledge from our conversation What should we save from this discussion?
🤖 AI-Assisted Collection

Claude can help you identify the most valuable knowledge to save, explain why certain items are valuable, and suggest appropriate tags and categories.

WebUI Access

In the web interface, click the "Collect Knowledge" button in the top toolbar.

Features

  • Visual Cards: Each detected item shown as a card with preview
  • Batch Selection: Click checkboxes or use "Select All"
  • Inline Editing: Edit title, tags, and type before saving
  • Preview Mode: See full markdown content before confirming
  • Score Indicators: Color-coded confidence levels (green = high, yellow = medium)
📝 Status

Coming in v0.2.0 (expected: 2 months) - This feature is currently under development. See CAPTURE_DESIGN_V2.md for full design specifications.

🤖

bg

v0.2.0

Manage background auto-collection with progressive refinement for token efficiency.

CLI Usage

# Show status (default) thinkbank bg # Start background collection thinkbank bg --start thinkbank bg --start --sensitivity high # Stop collection thinkbank bg --stop # Review suggestions thinkbank bg --review thinkbank bg --review --today

Flags

Flag Description Additional Options
--start Start background collection --sensitivity (low/medium/high)
--stop Stop background collection None
--status Show status (default if no flags) None
--review Review pending AI suggestions --today (show only today)

Sensitivity Levels

Level Threshold Description
Low ≥ 0.80 Conservative - Only capture highly confident items
Medium ≥ 0.70 Balanced - Recommended for most users
High ≥ 0.60 Aggressive - Capture more suggestions for review

Progressive Refinement Strategy

Background collection uses a token-efficient "coarse-to-fine" approach:

  1. Rule Matching (0 tokens): Quick pattern detection filters 90% of messages
  2. Coarse Scan (~500 tokens): Haiku analyzes compressed context every 10 messages
  3. Fine Dig (~2000 tokens): Sonnet deeply analyzes only "hot zones" (5-10% of messages)

Token Efficiency: 91% reduction vs full analysis
Average Cost: ~150 tokens per message
Accuracy: 90% (vs 95% for full Sonnet analysis)

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Background Collection Status ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Status: Running ✓ Sensitivity: medium (≥0.70) Uptime: 3h 24m Today's Activity: • Messages analyzed: 156 • Hot zones detected: 8 • Items auto-saved: 3 • Pending suggestions: 2 • Token usage: 23,400 (~150/msg) Recent Captures: ✓ 14:20 - SKILL: Database Indexing (0.87) ✓ 15:45 - PATTERN: Error Handling (0.82) ? 16:10 - LESSON: Async Pitfall (0.73) [Review] [Review Pending] [Adjust Settings] [Stop] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 When to Use

Enable background collection for continuous, hands-free knowledge capture during long work sessions. Perfect for "set it and forget it" operation.

Claude Chat Usage

# Start/stop background collection /thinkbank bg --start /thinkbank bg --stop # Check status /thinkbank bg # Natural language Enable background knowledge collection Show me what knowledge was captured today
🤖 AI Notifications

When background collection detects high-value knowledge (≥0.85), Claude will show a minimal notification. Medium-confidence items (0.70-0.85) are queued for batch review.

Notification Styles

# Minimal (default) - Non-intrusive ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 ThinkBank: Pattern detected (0.88) → Save "Error Handling Pattern"? [y/N] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # Silent - Auto-save with brief note ✓ Saved to ThinkBank [Details] [Undo] # Full - Detailed context (configurable) ╭─────────────────────────────────╮ │ 💡 ThinkBank Suggestion │ ├─────────────────────────────────┤ │ Type: pattern │ │ Title: Error Handling │ │ Confidence: High (0.88) │ │ Reason: Reusable with high │ │ specificity │ │ [Save] [Not now] [Details] │ ╰─────────────────────────────────╯

WebUI Access

In the web interface, navigate to Settings → Auto-Collection to configure background collection.

Dashboard Features

  • Live Status: Real-time monitoring of collection activity
  • Token Metrics: Visualize token usage and savings
  • Capture History: Timeline of all captured knowledge
  • Pending Queue: Review and approve/reject suggestions
  • Sensitivity Slider: Adjust threshold with live preview
  • Notification Settings: Choose minimal/full/silent styles
📝 Status

Coming in v0.2.0 (expected: 2 months) - This feature is currently under development. See CAPTURE_DESIGN_V2.md for full implementation details.

📦

export

Export knowledge items to a portable .khb (Knowledge Hub Bundle) file for backup or sharing.

CLI Usage

# Export all items thinkbank export my_knowledge.khb # Export with filters thinkbank export skills_pack.khb --type skill --min-score 0.8 # Export with metadata thinkbank export team_pack.khb \ --name "Team Knowledge Base" \ --author "Dev Team" \ --description "Shared knowledge and best practices" # Preview before exporting thinkbank export preview.khb --preview # Export as YAML format thinkbank export pack.khb --format yaml

Parameters

Parameter Type Required Description
output path Yes Output file path (.khb extension)
--type string No Filter by knowledge type
--min-score float No Minimum quality score
--tags string No Comma-separated tags
--limit integer No Maximum items to export
--name string No Pack name for metadata
--author string No Author name
--description string No Pack description
--format json|yaml No Export format (default: json)
--preview flag No Preview without exporting

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ Export Complete Items: 25 File: team_pack.khb Size: 487 KB Metadata: Name: Team Knowledge Base Author: Dev Team Created: 2026-02-06T10:30:00Z ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Claude Chat Usage

# Export with Claude /thinkbank export my_pack.khb --type skill # Natural language Export all high-quality Python skills to a pack
🤖 AI-Assisted Export

Claude can help you decide what to export based on your needs, suggest appropriate filters, and provide context about the exported knowledge.

WebUI Export

Navigate to Settings → Export/Import to export knowledge packs visually.

Features

  • Visual Selection: Check boxes to select specific items
  • Filter Preview: See real-time count of items to export
  • Metadata Form: Fill in pack name, author, description
  • Format Selection: Choose JSON or YAML export format
  • Download: Export and download directly from browser
📥

import

Import knowledge from a .khb file with automatic conflict resolution.

CLI Usage

# Import with interactive conflict resolution thinkbank import team_pack.khb # Import with automatic conflict handling thinkbank import pack.khb --conflict skip thinkbank import pack.khb --conflict overwrite thinkbank import pack.khb --conflict merge thinkbank import pack.khb --conflict rename # Preview before importing (dry run) thinkbank import pack.khb --dry-run

Parameters

Parameter Type Required Description
pack_path path Yes Path to .khb file
--conflict strategy No skip, overwrite, merge, rename, ask (default)
--dry-run flag No Preview without importing

Conflict Resolution Strategies

Strategy Behavior Use Case
skip Keep existing, ignore new Preserve local changes
overwrite Replace existing with new Trust imported version
merge Combine metadata, keep higher score Intelligent merging
rename Create new with unique ID Keep both versions
ask Prompt for each conflict Manual control

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ Import Complete Pack: Team Knowledge Base Author: Dev Team Results: Total Items: 25 Imported: 20 Skipped: 3 Conflicts: 2 Errors: 0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Backup Recommendation

ThinkBank automatically backs up your knowledge base before import. Backups are stored in ~/.thinkbank/backups/ and can be restored if needed.

Claude Chat Usage

# Import pack /thinkbank import team_pack.khb # Import with conflict strategy /thinkbank import pack.khb --conflict merge # Natural language Import the team knowledge pack and merge conflicts
🤖 AI-Assisted Conflict Resolution

When using Claude Chat with --conflict ask, Claude can help you decide how to handle conflicts by analyzing the differences and recommending the best strategy.

WebUI Import

Navigate to Settings → Export/Import and use the import wizard.

Features

  • Drag & Drop: Drag .khb file into import area
  • Preview: See pack contents before importing
  • Conflict Review: Visual diff for conflicting items
  • Selective Import: Choose which items to import
  • Progress Tracking: Real-time import progress bar

Knowledge Types

ThinkBank organizes knowledge into six semantic types, each optimized for different use cases:

💡 Skill

Technical skills and how-tos

Examples: "JWT implementation", "React hooks patterns", "Database indexing strategies"

📋 Rule

Best practices and guidelines

Examples: "API design principles", "Security checklist", "Code review standards"

🔄 Pattern

Reusable code/design patterns

Examples: "Repository pattern", "Factory pattern", "Observer pattern"

🌐 Domain

Domain-specific knowledge

Examples: "E-commerce checkout flows", "Healthcare compliance", "Financial regulations"

👤 User

User preferences and habits

Examples: "Preferred tech stack", "Code style preferences", "Workflow habits"

📖 Lesson

Lessons learned from mistakes

Examples: "Why X approach failed", "What worked in project Y", "Debugging war stories"

Quality Scoring

ThinkBank automatically evaluates each knowledge item with a quality score (0.0-1.0) based on five factors:

🔄 Reusability

How broadly applicable is this knowledge across different contexts?

🎯 Specificity

Level of concrete detail and actionable information.

🤖 AI Blind Spot

Information AI models might not know (project-specific, recent developments).

💥 Impact

Potential value and importance of the knowledge.

⏳ Decay

How quickly this knowledge becomes outdated (inverted - higher is better).

Score Ranges

Score Range Quality Level Recommendation
0.9 - 1.0 Exceptional Critical knowledge, share with team
0.8 - 0.9 Excellent High-value, reapply frequently
0.7 - 0.8 Good Worth keeping, review periodically
0.5 - 0.7 Fair Context-specific, may need refinement
< 0.5 Low Consider archiving or improving
💡 Using Score Filters

Use --min-score 0.8 in list, search, and export commands to focus on high-quality knowledge. This is especially useful when sharing knowledge packs with your team.

File Structure

ThinkBank stores all data in ~/.thinkbank/ with organized subdirectories:

~/.thinkbank/ ├── knowledge/ # Knowledge base (main storage) │ ├── skills/ # Technical skills │ ├── rules/ # Best practices │ ├── patterns/ # Design patterns │ ├── domain/ # Domain knowledge │ ├── user/ # User preferences │ └── lessons/ # Lessons learned │ ├── packs/ # Knowledge pack management │ ├── exported/ # Exported .khb files │ └── imported/ # Import backups │ ├── cache/ # Performance optimization │ └── search_index.db # Search index │ ├── logs/ # Operation logs │ └── thinkbank.log │ └── config/ # Configuration └── settings.yaml

Knowledge Item Format

Each knowledge item is stored as a markdown file with YAML frontmatter:

--- id: skill_fastapi_001 type: skill title: FastAPI Performance Optimization score: 0.87 tags: [python, api, performance] created: 2026-02-06T10:30:00Z factors: reusability: 0.9 specificity: 0.85 ai_blind_spot: 0.8 impact: 0.9 decay: 0.8 --- # FastAPI Performance Optimization ## Key Techniques - Use async/await for I/O operations - Enable Uvicorn workers - Implement response caching ...
✨ Direct File Access

You can manually create or edit knowledge items by adding/modifying .md files in the appropriate subdirectory. ThinkBank will automatically detect changes on next scan.

↑ Back to Top