sapper-iq 1.1.40 → 1.2.1
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.
- package/README.md +224 -158
- package/package.json +7 -3
- package/sapper-ui.mjs +2047 -1836
- package/sapper.mjs +1 -1
package/README.md
CHANGED
|
@@ -1,73 +1,94 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# Sapper
|
|
2
4
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/sapper-iq)
|
|
5
|
+
**Terminal-first AI coding assistant powered by local Ollama models.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/sapper-iq)
|
|
8
|
+
[](https://www.npmjs.com/package/sapper-iq)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](#)
|
|
12
|
+
|
|
13
|
+
[Install](#installation) · [Quick Start](#quick-start) · [Commands](#commands) · [Tools](#tool-catalog) · [Voice](#voice--whisper) · [Config](#configuration)
|
|
14
|
+
|
|
15
|
+
</div>
|
|
7
16
|
|
|
8
|
-
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
Sapper is a Node.js CLI that pairs with locally-running Ollama models to act as an autonomous development agent. It reads and writes files, runs shell commands, manages git, browses the web, and now transcribes your voice — all from a single conversational loop in your terminal.
|
|
9
20
|
|
|
10
|
-
|
|
21
|
+
> **100% local. 100% private. Zero telemetry.** Your code, prompts, and audio never leave your machine.
|
|
11
22
|
|
|
12
23
|
---
|
|
13
24
|
|
|
14
25
|
## Table of Contents
|
|
15
26
|
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
- [Features](#features)
|
|
19
|
-
- [Prerequisites](#prerequisites)
|
|
27
|
+
- [Highlights](#highlights)
|
|
28
|
+
- [Screens](#screens)
|
|
20
29
|
- [Installation](#installation)
|
|
21
30
|
- [Quick Start](#quick-start)
|
|
22
31
|
- [How It Works](#how-it-works)
|
|
23
32
|
- [Commands](#commands)
|
|
24
33
|
- [Tool Catalog](#tool-catalog)
|
|
25
|
-
- [
|
|
34
|
+
- [Voice / Whisper](#voice--whisper)
|
|
35
|
+
- [Agents & Skills](#agents--skills)
|
|
26
36
|
- [Configuration](#configuration)
|
|
27
37
|
- [Session Memory](#session-memory)
|
|
38
|
+
- [Project Layout](#project-layout)
|
|
28
39
|
- [Development](#development)
|
|
29
40
|
- [License](#license)
|
|
30
41
|
|
|
31
42
|
---
|
|
32
43
|
|
|
33
|
-
##
|
|
44
|
+
## Highlights
|
|
34
45
|
|
|
35
|
-
|
|
46
|
+
| | |
|
|
47
|
+
|---|---|
|
|
48
|
+
| **Local-first** | Connects to any Ollama model on your machine — no API keys, no cloud calls |
|
|
49
|
+
| **28+ built-in tools** | Files, shell, git, web, AST symbols, embeddings |
|
|
50
|
+
| **Native tool calling** | First-class support for Ollama's function-calling API, with a legacy text-marker fallback |
|
|
51
|
+
| **Voice input** | Talk to Sapper with Whisper (`/v live`) — interactive model picker, archive, push-to-stop, Arabic + multilingual |
|
|
52
|
+
| **Auto-summarization** | Compresses old turns when the context window fills, transparently |
|
|
53
|
+
| **Custom agents & skills** | Drop a Markdown file in `.sapper/agents/` or `.sapper/skills/` and it's live |
|
|
54
|
+
| **Background shell** | Long-running commands hand off to tracked background sessions you can read/stop |
|
|
55
|
+
| **Approval gate** | Inline approval prompts with feedback for shell and write operations |
|
|
56
|
+
| **Semantic memory** | Embedding-based recall surfaces relevant past context automatically |
|
|
57
|
+
| **Per-project state** | Everything lives in `.sapper/` — clean, portable, gitignore-friendly |
|
|
36
58
|
|
|
37
|
-
|
|
59
|
+
---
|
|
38
60
|
|
|
39
|
-
|
|
61
|
+
## Screens
|
|
62
|
+
|
|
63
|
+
### Startup Dashboard
|
|
64
|
+
|
|
65
|
+
On launch, Sapper shows the full state of your workspace before asking for input.
|
|
40
66
|
|
|
41
67
|
```
|
|
42
68
|
Sapper terminal coding workspace
|
|
43
69
|
Local models, live tools, and focused coding in one loop
|
|
44
|
-
/your/project · v1.1.
|
|
70
|
+
/your/project · v1.1.40
|
|
45
71
|
|
|
46
72
|
Quick start @file attach · /commands palette · /agents modes
|
|
47
73
|
|
|
48
74
|
┌──────────────────────────────────────────────────────────────┐
|
|
49
75
|
│ [workspace] 5 files · 0 symbols · indexed 36103m ago │
|
|
50
76
|
│ [memory] .sapper/ · auto-attach on │
|
|
51
|
-
│ [prompt] default prompt
|
|
52
|
-
│ [thinking] mode auto
|
|
53
|
-
│ [tools] limit 40 rounds
|
|
77
|
+
│ [prompt] default prompt │
|
|
78
|
+
│ [thinking] mode auto │
|
|
79
|
+
│ [tools] limit 40 rounds │
|
|
54
80
|
│ [shell] stream on · bg auto · 0 active │
|
|
55
|
-
│ [stream] heartbeat on · phases on
|
|
56
|
-
│ [summary] phases on · trigger 65%
|
|
57
|
-
│ [
|
|
81
|
+
│ [stream] heartbeat on · phases on │
|
|
82
|
+
│ [summary] phases on · trigger 65% │
|
|
83
|
+
│ [voice] whisper-cli · archive on │
|
|
84
|
+
│ [agents] 3 · [skills] 2 │
|
|
58
85
|
└──────────────────────────────────────────────────────────────┘
|
|
59
86
|
|
|
60
87
|
Previous session found in .sapper/context.json
|
|
61
88
|
Resume session? [y/N]
|
|
62
89
|
```
|
|
63
90
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
### Model Selection — Interactive Picker
|
|
69
|
-
|
|
70
|
-
Before each session, Sapper reads the locally available Ollama models and presents an interactive picker. Models are listed with their disk footprint and last-used time.
|
|
91
|
+
### Model Picker
|
|
71
92
|
|
|
72
93
|
```
|
|
73
94
|
Model selection use ↑↓ or j/k, enter to confirm
|
|
@@ -82,21 +103,11 @@ Preview
|
|
|
82
103
|
Selected gemma4:e4b-mlx-bf16
|
|
83
104
|
Footprint 14.9 GB
|
|
84
105
|
Updated 54m ago
|
|
85
|
-
Profile safetensors
|
|
86
|
-
Quant default
|
|
87
106
|
```
|
|
88
107
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
---
|
|
92
|
-
|
|
93
|
-
### Active Session — Context Bar
|
|
94
|
-
|
|
95
|
-
Once a model is selected the prompt loop begins. A persistent context bar at the bottom of each turn shows token consumption against the configured limit.
|
|
108
|
+
### Live Session
|
|
96
109
|
|
|
97
110
|
```
|
|
98
|
-
Session
|
|
99
|
-
|
|
100
111
|
[model] gemma4:e4b-mlx-bf16
|
|
101
112
|
[tools] native tool calling
|
|
102
113
|
[context] 35,000 tokens (custom limit, model: 131,072)
|
|
@@ -106,83 +117,38 @@ Session
|
|
|
106
117
|
>
|
|
107
118
|
```
|
|
108
119
|
|
|
109
|
-
The bar updates after every turn. When usage approaches the
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
### .sapper/ Data Folder
|
|
114
|
-
|
|
115
|
-
All persistent state is isolated inside `.sapper/` at the root of each project, keeping your workspace clean.
|
|
116
|
-
|
|
117
|
-
```
|
|
118
|
-
.sapper/
|
|
119
|
-
├── config.json runtime configuration (hot-reload)
|
|
120
|
-
├── context.json conversation history for session resume
|
|
121
|
-
├── embeddings.json semantic vector memory, cosine similarity recall
|
|
122
|
-
├── workspace.json file index and dependency graph
|
|
123
|
-
├── agents/ custom agent definitions (.md + YAML frontmatter)
|
|
124
|
-
├── skills/ reusable instruction blocks (.md + YAML frontmatter)
|
|
125
|
-
└── logs/ per-session activity audit logs (.md)
|
|
126
|
-
```
|
|
120
|
+
The context bar updates after every turn. When usage approaches the `summarizeTriggerPercent` threshold, Sapper compresses older turns into a summary and continues — no interruption.
|
|
127
121
|
|
|
128
122
|
---
|
|
129
123
|
|
|
130
124
|
## Architecture
|
|
131
125
|
|
|
132
126
|
```
|
|
133
|
-
|
|
134
|
-
│
|
|
135
|
-
│
|
|
136
|
-
│ User Input ──► Prompt Builder ──► Ollama
|
|
137
|
-
│
|
|
138
|
-
│
|
|
139
|
-
│
|
|
140
|
-
│
|
|
141
|
-
│
|
|
142
|
-
│
|
|
143
|
-
│
|
|
144
|
-
│
|
|
145
|
-
│ ▼
|
|
146
|
-
│
|
|
147
|
-
│
|
|
148
|
-
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
```
|
|
152
|
-
.sapper/
|
|
153
|
-
├── config.json ← Runtime configuration
|
|
154
|
-
├── context.json ← Conversation history
|
|
155
|
-
├── embeddings.json ← Vector memory store
|
|
156
|
-
├── workspace.json ← Project dependency graph
|
|
157
|
-
├── agents/ ← Custom agent definitions (.md)
|
|
158
|
-
├── skills/ ← Reusable skill definitions (.md)
|
|
159
|
-
└── logs/ ← Per-session activity logs (.md)
|
|
127
|
+
┌────────────────────────────────────────────────────────────────┐
|
|
128
|
+
│ SAPPER CLI │
|
|
129
|
+
│ │
|
|
130
|
+
│ User Input ──► Prompt Builder ──► Ollama (local) │
|
|
131
|
+
│ ▲ │ │ │
|
|
132
|
+
│ │ Context / Memory Streaming │
|
|
133
|
+
│ │ Embeddings Response │
|
|
134
|
+
│ │ Agent / Skills │ │
|
|
135
|
+
│ │ │ ▼ │
|
|
136
|
+
│ └──── Tool Parser ◄──── AI Response (native or text) │
|
|
137
|
+
│ │ │
|
|
138
|
+
│ ┌─────────┼──────────┬──────────┬────────────┐ │
|
|
139
|
+
│ ▼ ▼ ▼ ▼ ▼ │
|
|
140
|
+
│ File System Shell Git / Web Voice AST / Memory │
|
|
141
|
+
│ READ WRITE SHELL PUSH FETCH WHISPER SYMBOL RECALL │
|
|
142
|
+
└────────────────────────────────────────────────────────────────┘
|
|
160
143
|
```
|
|
161
144
|
|
|
162
145
|
---
|
|
163
146
|
|
|
164
|
-
## Features
|
|
165
|
-
|
|
166
|
-
| Area | Capability |
|
|
167
|
-
|---|---|
|
|
168
|
-
| AI Integration | Connects to any local Ollama model; model picker on startup |
|
|
169
|
-
| Tool Execution | 28 built-in tools covering files, shell, git, and web |
|
|
170
|
-
| Context Management | Auto-summarization when context window approaches limit |
|
|
171
|
-
| Session Memory | Embedding-based semantic memory with cosine similarity recall |
|
|
172
|
-
| Agents & Skills | Custom `.md` agent files with YAML frontmatter and tool restrictions |
|
|
173
|
-
| Background Shell | Long-running commands hand off to tracked background sessions |
|
|
174
|
-
| Approval Gate | Prompted approval with inline feedback for shell and write operations |
|
|
175
|
-
| Activity Logging | Every tool call and AI turn is logged to `.sapper/logs/` |
|
|
176
|
-
| AST Parsing | Symbol extraction (functions, classes) with `/symbol` search |
|
|
177
|
-
| Streaming | Live token-by-token output with heartbeat and phase status |
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
147
|
## Prerequisites
|
|
182
148
|
|
|
183
|
-
- [Node.js](https://nodejs.org)
|
|
184
|
-
- [Ollama](https://ollama.ai) installed and running locally
|
|
185
|
-
-
|
|
149
|
+
- **[Node.js](https://nodejs.org)** ≥ 16.0.0
|
|
150
|
+
- **[Ollama](https://ollama.ai)** installed and running locally with at least one model
|
|
151
|
+
- *(optional, for voice)* **[whisper.cpp](https://github.com/ggerganov/whisper.cpp)** and **ffmpeg** — see [Voice / Whisper](#voice--whisper)
|
|
186
152
|
|
|
187
153
|
```bash
|
|
188
154
|
ollama pull llama3
|
|
@@ -196,26 +162,39 @@ ollama pull llama3
|
|
|
196
162
|
npm install -g sapper-iq
|
|
197
163
|
```
|
|
198
164
|
|
|
165
|
+
Or run it without installing:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npx sapper-iq
|
|
169
|
+
```
|
|
170
|
+
|
|
199
171
|
---
|
|
200
172
|
|
|
201
173
|
## Quick Start
|
|
202
174
|
|
|
203
175
|
```bash
|
|
176
|
+
cd /path/to/your/project
|
|
204
177
|
sapper
|
|
205
178
|
```
|
|
206
179
|
|
|
207
|
-
|
|
180
|
+
Pick a model, then start talking:
|
|
208
181
|
|
|
209
182
|
```
|
|
210
|
-
|
|
211
|
-
Working directory: /your/project
|
|
212
|
-
|
|
213
|
-
> analyze this project and list what it does
|
|
183
|
+
> analyze this project and tell me what it does
|
|
214
184
|
> add a REST endpoint for user authentication
|
|
215
185
|
> run the tests and fix any failures
|
|
216
186
|
> commit the changes with a descriptive message
|
|
217
187
|
```
|
|
218
188
|
|
|
189
|
+
Or use your voice:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
> /v lang en
|
|
193
|
+
> /v live
|
|
194
|
+
🔴 Live preview — press any key to stop.
|
|
195
|
+
> [you speak] → transcript is sent to the AI
|
|
196
|
+
```
|
|
197
|
+
|
|
219
198
|
---
|
|
220
199
|
|
|
221
200
|
## How It Works
|
|
@@ -260,40 +239,64 @@ User prompt
|
|
|
260
239
|
|
|
261
240
|
## Commands
|
|
262
241
|
|
|
263
|
-
Run these inside Sapper at the prompt
|
|
242
|
+
Run these inside Sapper at the prompt. Press `Tab` for slash-command autocomplete.
|
|
243
|
+
|
|
244
|
+
### Session
|
|
264
245
|
|
|
265
246
|
| Command | Description |
|
|
266
247
|
|---|---|
|
|
267
|
-
| `/help` | Show the full command palette |
|
|
268
|
-
| `/
|
|
269
|
-
| `Tab` | Autocomplete slash commands while typing |
|
|
270
|
-
| `/reset` | Start a new conversation session |
|
|
271
|
-
| `/clear-session` | Alias for `/reset` |
|
|
248
|
+
| `/help`, `/commands` | Show the full command palette |
|
|
249
|
+
| `/reset`, `/clear-session` | Start a new conversation session |
|
|
272
250
|
| `/session-info` | Display current session metadata |
|
|
273
|
-
| `/summary` | View or change auto-summarization settings |
|
|
274
|
-
| `/summary phases off` | Hide summarization step list |
|
|
275
|
-
| `/summary trigger 60` | Set summarization trigger to 60 % of context |
|
|
276
|
-
| `/ui` | Show current frontend style and compact mode |
|
|
277
|
-
| `/ui style clean` | Switch to a cleaner Codex/OpenCode-like frontend style |
|
|
278
|
-
| `/ui style ultra` | Switch to an ultra-clean single-line frontend style |
|
|
279
|
-
| `/ui style sapper` | Switch back to the default Sapper frontend style |
|
|
280
|
-
| `/ui compact auto` | Set responsive compact rendering mode |
|
|
281
|
-
| `/shell` | Inspect shell config and list tracked background sessions |
|
|
282
|
-
| `/shell read <id>` | Read buffered output from a background session |
|
|
283
|
-
| `/shell stop <id>` | Stop a tracked background shell session |
|
|
284
|
-
| `/step` | Toggle step-by-step tool approval mode |
|
|
285
|
-
| `/tools` | Browse the built-in tool catalog |
|
|
286
|
-
| `/git` | Inspect repository state and git shortcuts |
|
|
287
|
-
| `/symbol <name>` | Search for a code symbol via AST index |
|
|
288
|
-
| `/recall <query>` | Search semantic memory for past context |
|
|
289
|
-
| `/memory` | Inspect markdown long-memory notes |
|
|
290
|
-
| `/memory add <title> ::: <note> ::: <tags>` | Save durable project notes/patterns in markdown |
|
|
291
|
-
| `/memory search <query>` | Search markdown long-memory notes |
|
|
292
251
|
| `/log` | View the current session activity log |
|
|
293
252
|
| `/attach <file>` | Attach a file to the next prompt |
|
|
294
253
|
| `//text` | Send literal text that starts with `/` |
|
|
295
254
|
| `exit` | Exit Sapper |
|
|
296
255
|
|
|
256
|
+
### Model & Tools
|
|
257
|
+
|
|
258
|
+
| Command | Description |
|
|
259
|
+
|---|---|
|
|
260
|
+
| `/model` | Switch the active Ollama model mid-session |
|
|
261
|
+
| `/tools` | Browse the built-in tool catalog |
|
|
262
|
+
| `/step` | Toggle step-by-step tool approval mode |
|
|
263
|
+
| `/symbol <name>` | Search for a code symbol via the AST index |
|
|
264
|
+
|
|
265
|
+
### Memory
|
|
266
|
+
|
|
267
|
+
| Command | Description |
|
|
268
|
+
|---|---|
|
|
269
|
+
| `/recall <query>` | Search semantic embeddings for past context |
|
|
270
|
+
| `/memory` | Inspect markdown long-memory notes |
|
|
271
|
+
| `/memory add <title> ::: <note> ::: <tags>` | Save a durable project note |
|
|
272
|
+
| `/memory search <query>` | Search markdown long-memory notes |
|
|
273
|
+
|
|
274
|
+
### Voice
|
|
275
|
+
|
|
276
|
+
| Command | Description |
|
|
277
|
+
|---|---|
|
|
278
|
+
| `/v`, `/voice` | Show voice status and settings |
|
|
279
|
+
| `/v live`, `/v stream` | Live preview while you speak, clean final transcript on stop |
|
|
280
|
+
| `/v record [seconds]` | Record from mic (push-to-stop, or fixed duration) |
|
|
281
|
+
| `/v talk` | Alias for push-to-stop recording |
|
|
282
|
+
| `/v file <path>` | Transcribe an existing audio file |
|
|
283
|
+
| `/v model` | Interactive picker — list available Whisper models |
|
|
284
|
+
| `/v lang <code>` | Lock language (e.g. `en`, `ar`, `auto`) |
|
|
285
|
+
| `/v archive on\|off\|open` | Toggle or reveal the recordings archive |
|
|
286
|
+
|
|
287
|
+
### Shell, UI & Summary
|
|
288
|
+
|
|
289
|
+
| Command | Description |
|
|
290
|
+
|---|---|
|
|
291
|
+
| `/shell` | Inspect shell config and tracked background sessions |
|
|
292
|
+
| `/shell read <id>` | Read buffered output from a background session |
|
|
293
|
+
| `/shell stop <id>` | Stop a tracked background shell session |
|
|
294
|
+
| `/git` | Inspect repository state and git shortcuts |
|
|
295
|
+
| `/summary` | View or change auto-summarization settings |
|
|
296
|
+
| `/summary trigger 60` | Set summarization trigger to 60 % of context |
|
|
297
|
+
| `/ui style sapper\|clean\|ultra` | Switch the frontend style |
|
|
298
|
+
| `/ui compact auto\|on\|off` | Responsive compact rendering |
|
|
299
|
+
|
|
297
300
|
---
|
|
298
301
|
|
|
299
302
|
## Tool Catalog
|
|
@@ -352,7 +355,56 @@ Run these inside Sapper at the prompt:
|
|
|
352
355
|
|
|
353
356
|
---
|
|
354
357
|
|
|
355
|
-
##
|
|
358
|
+
## Voice / Whisper
|
|
359
|
+
|
|
360
|
+
Sapper can transcribe your voice using local [whisper.cpp](https://github.com/ggerganov/whisper.cpp). Nothing is sent to the cloud — audio and transcripts stay on your machine.
|
|
361
|
+
|
|
362
|
+
### Setup (macOS)
|
|
363
|
+
|
|
364
|
+
```bash
|
|
365
|
+
brew install whisper-cpp ffmpeg
|
|
366
|
+
mkdir -p ~/models
|
|
367
|
+
curl -L -o ~/models/ggml-large-v3-turbo.bin \
|
|
368
|
+
https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
Then in Sapper:
|
|
372
|
+
|
|
373
|
+
```
|
|
374
|
+
/v model # pick from auto-detected models
|
|
375
|
+
/v lang ar # lock language for best quality (or 'en', 'auto', etc.)
|
|
376
|
+
/v live # press any key to stop, transcript goes to AI
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### Modes
|
|
380
|
+
|
|
381
|
+
| Mode | What it does |
|
|
382
|
+
|---|---|
|
|
383
|
+
| `/v live` | Streams a live preview as you speak, then runs one clean pass on the full WAV for the final transcript |
|
|
384
|
+
| `/v record` | Push-to-stop recording with live ticker |
|
|
385
|
+
| `/v record 8` | Fixed N-second capture |
|
|
386
|
+
| `/v file <path>` | Transcribe an existing audio file |
|
|
387
|
+
|
|
388
|
+
### Archive
|
|
389
|
+
|
|
390
|
+
Every recording is saved (when archive is on) to:
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
<project>/.sapper/voice/YYYY-MM-DD/HHMMSS-<mode>.{wav,txt}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
Use `/v archive open` to reveal it in Finder, `/v archive off` to disable.
|
|
397
|
+
|
|
398
|
+
### Quality tips
|
|
399
|
+
|
|
400
|
+
- **Lock the language** with `/v lang <code>` — `auto` works but per-chunk detection can bleed between languages
|
|
401
|
+
- Use **`ggml-large-v3-turbo`** for the best speed/quality trade-off (~1.5 GB)
|
|
402
|
+
- `large-v3` is slower but slightly more accurate (~2.9 GB)
|
|
403
|
+
- Sapper auto-strips common silence hallucinations (`[BLANK_AUDIO]`, `"you"`, `"Thank you."`, subtitle credits, etc.)
|
|
404
|
+
|
|
405
|
+
---
|
|
406
|
+
|
|
407
|
+
## Agents & Skills
|
|
356
408
|
|
|
357
409
|
Sapper supports custom agents and reusable skills defined as Markdown files with YAML frontmatter, stored in `.sapper/agents/` and `.sapper/skills/`.
|
|
358
410
|
|
|
@@ -465,27 +517,33 @@ Configuration is hot-reloaded — edit the file while Sapper is running and chan
|
|
|
465
517
|
|
|
466
518
|
## Session Memory
|
|
467
519
|
|
|
468
|
-
Sapper maintains
|
|
520
|
+
Sapper maintains three layers of memory per project — all stored locally under `.sapper/`:
|
|
521
|
+
|
|
522
|
+
| Layer | File | Purpose |
|
|
523
|
+
|---|---|---|
|
|
524
|
+
| **Short-term** | `.sapper/context.json` | Full conversation history; auto-summarized as the context window fills |
|
|
525
|
+
| **Semantic** | `.sapper/embeddings.json` | Chunked text with cosine-similarity recall; auto-surfaced on relevant prompts. Search with `/recall <query>` |
|
|
526
|
+
| **Durable** | `.sapper/long-memory.md` | Markdown project patterns, decisions, fixes. Managed with `/memory add` / `/memory search` |
|
|
527
|
+
|
|
528
|
+
Every tool call and AI turn is also logged to `.sapper/logs/session-<timestamp>.md` for auditing.
|
|
529
|
+
|
|
530
|
+
---
|
|
531
|
+
|
|
532
|
+
## Project Layout
|
|
469
533
|
|
|
470
534
|
```
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
│ Durable notes → .sapper/long-memory.md │
|
|
482
|
-
│ Markdown project patterns/decisions/fixes │
|
|
483
|
-
│ Managed with /memory add, /memory search, /memory │
|
|
484
|
-
└─────────────────────────────────────────────────────┘
|
|
535
|
+
.sapper/
|
|
536
|
+
├── config.json runtime configuration (hot-reload, JSONC)
|
|
537
|
+
├── context.json conversation history for session resume
|
|
538
|
+
├── embeddings.json semantic vector memory
|
|
539
|
+
├── workspace.json file index and dependency graph
|
|
540
|
+
├── long-memory.md durable project notes
|
|
541
|
+
├── voice/ audio + transcript archive (YYYY-MM-DD/)
|
|
542
|
+
├── agents/ custom agents (.md + YAML frontmatter)
|
|
543
|
+
├── skills/ reusable skill blocks (.md + YAML frontmatter)
|
|
544
|
+
└── logs/ per-session activity audit logs
|
|
485
545
|
```
|
|
486
546
|
|
|
487
|
-
All activity is also written to `.sapper/logs/session-<timestamp>.md` for auditing.
|
|
488
|
-
|
|
489
547
|
---
|
|
490
548
|
|
|
491
549
|
## Development
|
|
@@ -498,16 +556,24 @@ chmod +x sapper.mjs
|
|
|
498
556
|
node sapper.mjs
|
|
499
557
|
```
|
|
500
558
|
|
|
501
|
-
CI runs
|
|
559
|
+
CI runs on push to `main` across Node.js 16, 18, and 20.
|
|
560
|
+
|
|
561
|
+
### Releasing
|
|
562
|
+
|
|
563
|
+
See [PUBLISHING.md](PUBLISHING.md) for the full npm release flow.
|
|
502
564
|
|
|
503
565
|
---
|
|
504
566
|
|
|
505
567
|
## License
|
|
506
568
|
|
|
507
|
-
MIT — see [LICENSE](LICENSE)
|
|
569
|
+
MIT — see [LICENSE](LICENSE).
|
|
508
570
|
|
|
509
571
|
---
|
|
510
572
|
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
**
|
|
573
|
+
<div align="center">
|
|
574
|
+
|
|
575
|
+
**Built by [Ibrahim Ihsan](https://github.com/aledanee)** · [npm](https://www.npmjs.com/package/sapper-iq) · [GitHub](https://github.com/aledanee/sapper) · [Issues](https://github.com/aledanee/sapper/issues)
|
|
576
|
+
|
|
577
|
+
<sub>If Sapper saves you time, a ⭐ on GitHub means a lot.</sub>
|
|
578
|
+
|
|
579
|
+
</div>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sapper-iq",
|
|
3
|
-
"version": "1.1
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"description": "AI-powered development assistant that executes commands and builds projects",
|
|
5
5
|
"main": "sapper.mjs",
|
|
6
6
|
"bin": {
|
|
@@ -14,7 +14,9 @@
|
|
|
14
14
|
],
|
|
15
15
|
"type": "module",
|
|
16
16
|
"scripts": {
|
|
17
|
-
"start": "node sapper.mjs"
|
|
17
|
+
"start": "node sapper.mjs",
|
|
18
|
+
"ui": "node sapper-ui.mjs",
|
|
19
|
+
"postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'..','prebuilds','darwin-arm64','spawn-helper'),0o755)}catch(e){};try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'..','prebuilds','darwin-x64','spawn-helper'),0o755)}catch(e){}\""
|
|
18
20
|
},
|
|
19
21
|
"dependencies": {
|
|
20
22
|
"acorn": "^8.15.0",
|
|
@@ -22,8 +24,10 @@
|
|
|
22
24
|
"cli-highlight": "^2.1.11",
|
|
23
25
|
"marked": "^15.0.12",
|
|
24
26
|
"marked-terminal": "^7.3.0",
|
|
27
|
+
"node-pty": "^1.1.0",
|
|
25
28
|
"ollama": "^0.5.0",
|
|
26
|
-
"ora": "^8.0.1"
|
|
29
|
+
"ora": "^8.0.1",
|
|
30
|
+
"ws": "^8.21.0"
|
|
27
31
|
},
|
|
28
32
|
"engines": {
|
|
29
33
|
"node": ">=16.0.0"
|