clew-code 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +181 -113
  2. package/dist/generated/version.json +1 -1
  3. package/dist/main.js +2948 -3258
  4. package/package.json +1 -1
  5. package/docs/.nojekyll +0 -0
  6. package/docs/_config.yml +0 -3
  7. package/docs/architecture.html +0 -90
  8. package/docs/assets/clew-agent-loop.png +0 -0
  9. package/docs/assets/clew-general-architecture.png +0 -0
  10. package/docs/assets/clew-mcp-architecture.png +0 -0
  11. package/docs/assets/clew-p2p-swarm.png +0 -0
  12. package/docs/assets/clew.svg +0 -33
  13. package/docs/changelog.html +0 -141
  14. package/docs/cli-reference.html +0 -89
  15. package/docs/commands.html +0 -161
  16. package/docs/configuration.html +0 -85
  17. package/docs/contributing.html +0 -91
  18. package/docs/css/styles.css +0 -545
  19. package/docs/daemon.html +0 -62
  20. package/docs/features/bridge-mode.html +0 -62
  21. package/docs/features/evals.html +0 -58
  22. package/docs/features/searxng-search.html +0 -59
  23. package/docs/features/sentry-setup.html +0 -62
  24. package/docs/generated/providers.html +0 -625
  25. package/docs/generated/tools.html +0 -559
  26. package/docs/index.html +0 -182
  27. package/docs/installation.html +0 -77
  28. package/docs/internals/claude-ai-backend-dependencies.md +0 -278
  29. package/docs/internals/growthbook-ab-testing.html +0 -70
  30. package/docs/internals/hidden-features.html +0 -82
  31. package/docs/internals/long-term-memory-design.md +0 -173
  32. package/docs/js/main.js +0 -438
  33. package/docs/loop.html +0 -69
  34. package/docs/mcp.html +0 -99
  35. package/docs/models.html +0 -81
  36. package/docs/permission-model.html +0 -86
  37. package/docs/personal-profile.html +0 -113
  38. package/docs/plugins.html +0 -84
  39. package/docs/providers.html +0 -625
  40. package/docs/quick-start.html +0 -81
  41. package/docs/research-memory.html +0 -71
  42. package/docs/security.html +0 -71
  43. package/docs/skills.html +0 -67
  44. package/docs/swarm.html +0 -78
  45. package/docs/tools.html +0 -559
  46. package/docs/troubleshooting.html +0 -86
  47. package/docs/voice-mode.html +0 -79
package/docs/internals/hidden-features.html DELETED
@@ -1,82 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Hidden Features — Clew Code</title>
7
- <meta name="description" content="Undocumented features and power-user tips for Clew Code.">
8
- <link rel="icon" type="image/svg+xml" href="../assets/clew.svg">
9
- <link rel="preconnect" href="https://fonts.googleapis.com">
10
- <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
11
- <link rel="stylesheet" href="../css/styles.css">
12
- </head>
13
- <body>
14
- <header class="header"></header>
15
- <div id="sidebarOverlay" class="sidebar-overlay"></div>
16
- <aside id="sidebar" class="sidebar"></aside>
17
-
18
- <div class="content-wrap">
19
- <div class="content">
20
-
21
- <div class="breadcrumbs"><a href="../index.html">Home</a><span class="sep">/</span><span class="current">Hidden Features</span></div>
22
-
23
- <h1>Hidden Features</h1>
24
- <p class="sub">Power-user features and undocumented capabilities.</p>
25
-
26
- <h2 id="thinkback">Thinkback</h2>
27
- <p>Record and replay session interactions for debugging and analysis:</p>
28
- <pre><code class="language-bash">❯ /thinkback # record a session
29
- ❯ /thinkback-play # replay a recorded session
30
- </code></pre>
31
-
32
- <h2 id="goal">Goal Tracking</h2>
33
- <p>Set and track development goals across sessions:</p>
34
- <pre><code class="language-bash">❯ /goal set "ship v0.3 by Friday"
35
- ❯ /goal status
36
- ❯ /goal list
37
- </code></pre>
38
-
39
- <h2 id="btw">BTW (By The Way)</h2>
40
- <p>Leave contextual notes and reminders for future sessions:</p>
41
- <pre><code class="language-bash">❯ /btw "remember to update the CI config"
42
- </code></pre>
43
-
44
- <h2 id="desktop-handoff">Desktop Handoff / Teleport</h2>
45
- <p>Move a running session between machines:</p>
46
- <pre><code class="language-bash">❯ /remote-setup # prepare for handoff
47
- ❯ /remote-env # transfer environment
48
- </code></pre>
49
-
50
- <h2 id="passes">Passes</h2>
51
- <p>View pass/interaction history for the current session:</p>
52
- <pre><code class="language-bash">❯ /passes
53
- </code></pre>
54
-
55
- <h2 id="recap">Recap</h2>
56
- <p>Generate a summary of the current session's key decisions and actions:</p>
57
- <pre><code class="language-bash">❯ /recap
58
- </code></pre>
59
-
60
- <h2 id="sandbox">Sandbox Toggle</h2>
61
- <p>Toggle sandbox mode for secure command execution:</p>
62
- <pre><code class="language-bash">❯ /sandbox on
63
- ❯ /sandbox off
64
- </code></pre>
65
-
66
- <h2 id="theme">Color Theme</h2>
67
- <p>Customize the terminal color theme:</p>
68
- <pre><code class="language-bash">❯ /theme # interactive theme picker
69
- ❯ /color # set specific colors
70
- </code></pre>
71
-
72
- <h2 id="scroll-speed">Scroll Speed</h2>
73
- <p>Adjust terminal output scroll speed:</p>
74
- <pre><code class="language-bash">❯ /scroll-speed fast
75
- ❯ /scroll-speed slow
76
- </code></pre>
77
- </div>
78
- </div>
79
-
80
- <script src="../js/main.js"></script>
81
- </body>
82
- </html>
package/docs/internals/long-term-memory-design.md DELETED
@@ -1,173 +0,0 @@
1
- # Long-Term Memory System Implementation
2
-
3
- ## Architecture
4
-
5
- ```
6
- ~/.clew/projects/<project-root>/
7
- ├── session-memory.db ← SQLite (bun:sqlite)
8
- │ ├── sessions ← session records + consolidation level
9
- │ ├── topic_index ← tag → session mapping
10
- │ └── digests ← weekly/monthly summaries
11
- ├── memory/ ← Auto-memory directory (MEMORY.md + topic files)
12
- │ ├── MEMORY.md ← Entrypoint, loaded into system prompt
13
- │ └── ... ← Other markdown memory files
14
- └── sessions/
15
- └── <sessionId>/
16
- └── checkpoints/ ← Structured checkpoint files
17
- ├── index.json ← Lightweight index
18
- ├── cycle.txt ← Current rebuild cycle number
19
- ├── notes.md ← Main agent's append-only scratchpad
20
- ├── 20-<id>.json ← 20% progress checkpoint
21
- ├── 45-<id>.json ← 45% progress checkpoint
22
- └── 70-<id>.json ← 70% progress checkpoint (triggers MEMORY.md promotion)
23
- ```
24
-
25
- ### Database Schema
26
-
27
- ```sql
28
- -- Each session
29
- CREATE TABLE sessions (
30
- session_id TEXT PRIMARY KEY,
31
- start_time INTEGER, end_time INTEGER,
32
- model TEXT, provider TEXT,
33
- summary TEXT,
34
- key_decisions TEXT, -- JSON array
35
- active_files TEXT, -- JSON array
36
- tags TEXT, -- JSON array
37
- consolidated INTEGER DEFAULT 0 -- 0=raw, 1=weekly, 2=monthly
38
- );
39
-
40
- -- Topic → session index
41
- CREATE TABLE topic_index (
42
- topic TEXT NOT NULL,
43
- session_id TEXT NOT NULL,
44
- PRIMARY KEY(topic, session_id)
45
- );
46
-
47
- -- Weekly/monthly digests
48
- CREATE TABLE digests (
49
- period TEXT NOT NULL, -- '2026-W24' or '2026-06'
50
- type TEXT NOT NULL, -- 'weekly' or 'monthly'
51
- summary TEXT,
52
- patterns TEXT, -- recurring patterns detected
53
- session_count INTEGER,
54
- created_at INTEGER,
55
- PRIMARY KEY(period, type)
56
- );
57
- ```
58
-
59
- ## Consolidation Flow
60
-
61
- ```
62
- saveSessionSummary()
63
- → INSERT session (consolidated=0)
64
- → UPDATE topic_index
65
- → consolidateIfNeeded()
66
- → SELECT sessions WHERE consolidated=0 AND end_time < 7d ago
67
- → GROUP BY ISO week, then by month
68
- → Generate weekly digest (patterns from tags + decisions)
69
- → Mark sessions consolidated=1
70
- → Generate monthly digest from weekly digests
71
- → Mark sessions consolidated=2
72
- ```
73
-
74
- ## Layered Memory
75
-
76
- Inspired by MiMo Code's 4-layer memory design. Each layer has a different lifecycle and persistence:
77
-
78
- | Layer | Storage | Lifecycle | Written by |
79
- |-------|---------|-----------|------------|
80
- | Session | `checkpoints/<id>.json` | Per-session, cleared on session end | Checkpoint Writer (inline) |
81
- | Notes | `checkpoints/notes.md` | Per-session, read + cleared at each checkpoint | Main agent (append-only) |
82
- | Project | `memory/MEMORY.md` | Cross-session, persists indefinitely | Checkpoint Promoter (70%), autoDream, manual |
83
- | Global | `MEMORY.md` at config root | Cross-project, persists indefinitely | autoDream, manual |
84
- | History | SQLite (`session-memory.db`) | Permanent, append-only | Session Logger |
85
-
86
- ### Session Checkpoint
87
-
88
- Triggered at 20%/45%/70% of goal's `maxTurns` budget. Written as fire-and-forget (`.catch(noop)`) so it never blocks the main loop.
89
-
90
- Fields: goalText, turnCount, elapsedMs, filesModified, commandsRun, decisions, currentBlockers, nextSteps, summary, cycle, notes.
91
-
92
- ### Notes Scratchpad
93
-
94
- `notes.md` is the main agent's **only** persistent write channel. The agent is told about it via system prompt when a goal is active. At each checkpoint, the writer reads notes and routes them into the structured checkpoint fields, then clears the scratchpad.
95
-
96
- ### Project Memory (MEMORY.md)
97
-
98
- At the 70% checkpoint, the Checkpoint Promoter promotes stable information into `MEMORY.md`:
99
- - Repeatedly modified files → "active files"
100
- - Persistent decisions → "architecture decisions"
101
- - Notes → "session notes"
102
-
103
- Promotion is fire-and-forget (non-blocking).
104
-
105
- ### Goal Verifier
106
-
107
- When the agent attempts to terminate with an active goal, an independent forked agent reviews the conversation against the goal text. If the goal isn't met, the gap is attached as `goalGap` in the result metadata. The verifier:
108
- - Does **not** participate in actual work (no alignment bias)
109
- - Receives the same context as the agent (actual tool outputs)
110
- - Returns `{ isComplete, gap?, isImpossible? }`
111
- - Failure is non-fatal — normal termination proceeds
112
-
113
- ## Files
114
-
115
- | File | Purpose |
116
- |------|---------|
117
- | `src/services/longTermMemory/crossSession.ts` | Core: save, load, consolidate, topic index |
118
- | `src/services/longTermMemory/timeline.ts` | Timeline queries, density stats, digest format |
119
- | `src/services/longTermMemory/consolidate.ts` | Preview/save consolidation candidates |
120
- | `src/services/longTermMemory/index.ts` | Barrel exports |
121
- | `src/services/checkpoint/checkpointWriter.ts` | Structured checkpoint system + notes scratchpad + cycle tracking |
122
- | `src/services/checkpoint/checkpointPromoter.ts` | Checkpoint → MEMORY.md promotion |
123
- | `src/services/goal/goalVerifier.ts` | Independent goal completion verification |
124
- | `src/services/maxMode/candidateRunner.ts` | Max Mode: parallel candidate selection with LLM judge |
125
- | `src/commands/maxMode/maxMode.tsx` | `/maxmode` command (on/off/candidates N) |
126
-
127
- ## Checkpoint Flow
128
-
129
- ```
130
- User turn → query() loop
131
- ↓
132
- Turn count crosses threshold (20/45/70%)?
133
- ↓ yes
134
- Extract decisions, commands, files from recent messages
135
- ↓
136
- Read notes.md + current cycle
137
- ↓
138
- Fire-and-forget writeCheckpoint() + clearNotes()
139
- ↓
140
- If threshold === 70%: promoteCheckpoints() → append to MEMORY.md
141
- ↓
142
- Continue query() loop
143
- ```
144
-
145
- ## Rebuild Cycle
146
-
147
- When context window fills, compact runs `tryRebuildFromCheckpoint()`. If a checkpoint exists, it builds a **layered context prompt** instead of a flat summary:
148
-
149
- ```
150
- Goal + Progress Metadata
151
- ↓
152
- Key Decisions + Files Modified + Commands Executed
153
- ↓
154
- Accumulated Notes (from scratchpad)
155
- ↓
156
- Phase Summary (if any)
157
- ↓
158
- Current Blockers + Next Steps
159
- ```
160
-
161
- Each rebuild increments `cycle`, so the model can see it's in a continued session window.
162
-
163
- ## Commands
164
-
165
- | Command | Action |
166
- |---------|--------|
167
- | `/memory save [summary]` | Save session + auto-consolidate old data |
168
- | `/memory timeline` | Show chronological session history |
169
- | `/memory stats` | Activity density chart |
170
- | `/memory digest` | Show weekly/monthly digests |
171
- | `/memory preview` | Preview sessions ready for consolidation |
172
- | `/memory consolidate` | Mark old sessions as consolidated |
173
- | `/maxmode on\|off\|candidates N` | Toggle parallel candidate selection |