Knowledge
A knowledge entry is the atomic unit in workthin. Each entry contains:
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier (e.g. 550e8400-e29b-41d4-a716-446655440000) |
title | string | Short, searchable title |
body | string | Free-form content — AI structures this into problem/solution/root cause |
scope | enum | Visibility: personal, project, global |
tags | string[] | Categorization labels (auto-generated and manual) |
prev_knowledge_id | UUID? | Links to a previous version (thought chaining) |
branch_from_id | UUID? | Links to the parent entry this was forked from |
url | string? | Reference URL (e.g. incident link, PR, docs) |
etag | string | Optimistic concurrency control token |
created_at | timestamp | Creation time |
updated_at | timestamp | Last update time |
Thought Chains
When a problem recurs or evolves, link knowledge entries together using prev_knowledge_id. This creates a chronological chain:
550e8400-... : Redis split-brain (initial)
└─ 660f9500-... : Redis split-brain (recurrence)
└─ 770a0600-... : Redis split-brain (final fix)Each entry in the chain preserves its own context while maintaining the full history of how a solution evolved.
Branches
Use branch_from_id to fork a knowledge entry and explore an alternative solution. Branches are independent — changes to the branch do not affect the original.
550e8400-... : OOM fix (set max-old-space-size)
├─ branch: 880b1700-... : OOM fix (use cgroups v2 memory limits)
└─ branch: 990c2800-... : OOM fix (switch to Bun runtime)Scopes
Scopes control who can see and use a knowledge entry.
| Scope | Visibility | Use Case |
|---|---|---|
personal | Only you | Personal notes, draft solutions |
project | Your project | Project-specific fixes and procedures |
global | Everyone | Company-wide knowledge base |
Joining a Project
There are two ways to join a project:
- Via git remote — Run
wt initin a repository. workthin detects the git remote and auto-creates or joins the matching project. Everyone who runswt initin the same repository joins the same project automatically. No invitation needed. - Via invitation — A project admin can invite existing workthin users by email from the project settings page. The invited user must already have a workthin account.
The project description is auto-generated from package.json when available.
Global Reads & Contributor Rewards
Global knowledge is read-limited on the Free tier (30 reads/month). Pro plan has unlimited reads.
A "global read" is counted each time your AI searches or retrieves a global-scoped knowledge entry. Personal and project-scoped reads are always free and unlimited.
How rewards work
Contributing to the global library earns additional reads on top of your monthly allowance:
| Action | Reward | When counted |
|---|---|---|
| Publish to global | +1.0 read | When you set scope to global |
| Viewed by others | +0.1 / view | When another user's AI retrieves your knowledge (5-hour cooldown per user per entry) |
| Referenced in search | +0.3 / reference | When your knowledge appears in another user's search results |
| Resolved a problem | +1.0 / resolution | When another user marks your knowledge as "this helped" |
| Branched by others | +0.5 | When someone forks your knowledge via branch_from_id |
| Quality flag (valid) | +0.5 | When a warning or deprecation comment you added is confirmed useful |
Rewards are credited instantly and accumulate throughout the month. The counter resets on the 1st of each month. Pro users earn rewards too, but since their reads are already unlimited, the rewards serve as a contribution score.
Example
You publish 3 knowledge entries to global (+3.0). Over the month, they get viewed 20 times (+2.0) and referenced in 10 searches (+3.0). Your effective monthly allowance becomes 30 + 8.0 = 38 global reads.
The more you contribute, the more you can read.
Detail Levels
Control how much information is returned in API responses.
| Level | Tokens | Content |
|---|---|---|
L1 (summary) | ~100 | title and solution summary only |
L2 (standard) | ~500 | L1 + full body, tags, metadata |
L3 (full) | ~2,000 | L2 + comments, thought chain history, branches |
Use the string values (summary, standard, full) in API and CLI calls. Default is summary. Use summary for chatbot integrations where token cost matters.
Comment Types
Knowledge entries support four comment types:
| Type | Purpose |
|---|---|
supplement | Additional context, tips, or edge cases |
warning | Caveats, known issues, or conditions where the solution fails |
deprecation | Mark the knowledge as outdated or superseded |
reference | Link to related knowledge, external docs, or resources |
Secret Protection
workthin runs a 3-stage secret masking pipeline before storing any knowledge:
- Regex stage — Pattern-based detection of common secret formats (API keys, tokens, connection strings, passwords)
- Entropy stage — High-entropy string detection catches secrets that don't match known patterns
- AI stage — LLM-based analysis identifies contextual secrets (e.g. internal hostnames, private IPs, proprietary identifiers)
All three stages run on every create and update operation. Detected secrets are masked with [MASKED:pattern_name] before storage.