@eleboucher/pi-memini 0.7.4 → 0.7.5
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 +206 -103
- package/dist/index.js +1117 -235
- package/package.json +22 -8
package/README.md
CHANGED
|
@@ -1,36 +1,24 @@
|
|
|
1
1
|
# memini + Pi
|
|
2
2
|
|
|
3
3
|
[Pi](https://pi.dev) is an open-source coding agent with a first-class
|
|
4
|
-
[extension API](https://pi.dev/docs/latest/extensions). Pi has
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
[extension API](https://pi.dev/docs/latest/extensions). Pi has no built-in MCP
|
|
5
|
+
client, so memini ships a native Pi package in [`plugin/`](plugin/). It adds
|
|
6
|
+
automatic session memory, native `memory_*` tools, lifecycle persistence, and
|
|
7
|
+
compact transcript rendering without an MCP adapter.
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Install
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The package is published as
|
|
12
|
+
[`@eleboucher/pi-memini`](https://www.npmjs.com/package/@eleboucher/pi-memini)
|
|
13
|
+
and requires Pi 0.80.6 or newer (Node.js 22.19 or newer):
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
echoed back a turn behind; past sessions still recall.
|
|
17
|
-
- **`agent_end`** — once the agent finishes a prompt, stores the completed
|
|
18
|
-
user/assistant turn back into memini (episodic, tagged `pi`, with the session
|
|
19
|
-
id) so it can be recalled later.
|
|
20
|
-
- **Explicit tools** — modeled on the tool set Claude Code gets from memini's
|
|
21
|
-
MCP server, registered natively via `pi.registerTool`: `memory_recall`, `memory_list`,
|
|
22
|
-
`memory_remember`, `memory_forget`. The model can call them on demand even
|
|
23
|
-
though the automatic loop already runs.
|
|
24
|
-
|
|
25
|
-
### Install
|
|
26
|
-
|
|
27
|
-
The extension is published to npm as
|
|
28
|
-
[`@eleboucher/pi-memini`](https://www.npmjs.com/package/@eleboucher/pi-memini).
|
|
29
|
-
Pi has no `init`/scaffold command — extensions are just discovered from known
|
|
30
|
-
locations or declared in config. Pick one:
|
|
15
|
+
```sh
|
|
16
|
+
pi install npm:@eleboucher/pi-memini
|
|
17
|
+
```
|
|
31
18
|
|
|
32
|
-
|
|
33
|
-
|
|
19
|
+
Use `-l` for a project-local install. Pi records global packages in
|
|
20
|
+
`~/.pi/agent/settings.json` and project packages in `.pi/settings.json`.
|
|
21
|
+
Equivalent manual configuration is:
|
|
34
22
|
|
|
35
23
|
```json
|
|
36
24
|
{
|
|
@@ -38,98 +26,213 @@ locations or declared in config. Pick one:
|
|
|
38
26
|
}
|
|
39
27
|
```
|
|
40
28
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
the built `dist/index.js` (or the `src/index.ts` source) there.
|
|
29
|
+
Project-local packages load only after the project is trusted. Run `pi config`
|
|
30
|
+
to enable or disable installed resources.
|
|
44
31
|
|
|
45
|
-
|
|
32
|
+
For development, load the built extension for one run:
|
|
46
33
|
|
|
47
34
|
```sh
|
|
35
|
+
npm --prefix integrations/pi/plugin run build
|
|
48
36
|
pi -e ./integrations/pi/plugin/dist/index.js
|
|
49
37
|
```
|
|
50
38
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
39
|
+
Pi also auto-discovers source extensions placed in
|
|
40
|
+
`~/.pi/agent/extensions/` or `.pi/extensions/`; those locations can be
|
|
41
|
+
hot-reloaded with `/reload`.
|
|
42
|
+
|
|
43
|
+
## What the extension does
|
|
44
|
+
|
|
45
|
+
### Automatic memory and lifecycle
|
|
46
|
+
|
|
47
|
+
- **`session_start` / `session_tree`** reconstruct branch-local suppression and
|
|
48
|
+
capture state, then inject one bounded layered briefing when the active model
|
|
49
|
+
context does not already contain it. Startup, resume, fork, and reload do not
|
|
50
|
+
duplicate an intact briefing.
|
|
51
|
+
- **`before_agent_start`** searches for the submitted prompt and injects useful
|
|
52
|
+
matches as untrusted, read-only context. Blank text, command-shaped prompts,
|
|
53
|
+
and steering text shorter than 12 characters are skipped; search queries are
|
|
54
|
+
capped at 2,000 characters.
|
|
55
|
+
- **`agent_settled`** captures the final successful user/assistant turn only
|
|
56
|
+
after retries, overflow compaction, and queued continuations have settled.
|
|
57
|
+
Repeated settled events for the same assistant entry are idempotent.
|
|
58
|
+
- **`session_before_compact` / `session_compact`** optionally checkpoint bounded
|
|
59
|
+
state-changing activity, clear context-coupled suppression, and queue a fresh
|
|
60
|
+
briefing without starting an extra turn.
|
|
61
|
+
- **`session_shutdown`** optionally records a bounded activity digest for real
|
|
62
|
+
shutdown/switch/fork events. Reload is skipped because the session continues.
|
|
63
|
+
- **Branch-aware dedupe** persists in Pi custom entries only after the matching
|
|
64
|
+
recall/tool-result message is finalized. Automatic briefing and prompt recall,
|
|
65
|
+
plus explicit recall/briefing/list/get/history/answer results, share one cooldown
|
|
66
|
+
state; successful updates, deletes, and ID upserts make corrected content eligible immediately,
|
|
67
|
+
even when sibling tools complete concurrently.
|
|
68
|
+
Set `MEMINI_INJECT_DEDUPE=0` to disable exclusions, filtering, and recording
|
|
69
|
+
together.
|
|
70
|
+
|
|
71
|
+
The server-authoritative namespace from `POST /v1/handshake` scopes automatic
|
|
72
|
+
and explicit requests through `X-Memini-Namespace`. Automatic lifecycle work
|
|
73
|
+
no-ops while authority is unavailable; explicit tools retry the handshake once
|
|
74
|
+
and then return an actionable error rather than request a locally guessed partition.
|
|
75
|
+
A compatibility retry drops `exclude_ids` only after a server explicitly rejects
|
|
76
|
+
that field with HTTP 400; timeouts, throttling, and unrelated failures do not disable it.
|
|
77
|
+
|
|
78
|
+
### Native tools
|
|
79
|
+
|
|
80
|
+
Pi registers these tools directly with `pi.registerTool`:
|
|
81
|
+
|
|
82
|
+
| Tool | Purpose |
|
|
83
|
+
| ----------------- | -------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `memory_briefing` | Read pinned context, durable facts, procedures, recent work, and nested-project rollups. |
|
|
85
|
+
| `memory_recall` | Hybrid semantic/keyword recall with filters, time travel, scope, exclusions, and provenance. |
|
|
86
|
+
| `memory_list` | Browse and page newest-first memories without a search query. |
|
|
87
|
+
| `memory_remember` | Store or upsert an atomic memory, including validity, confidence, metadata, and visibility. |
|
|
88
|
+
| `memory_get` | Fetch one complete memory DTO. |
|
|
89
|
+
| `memory_history` | Read a memory's supersession history oldest-first. |
|
|
90
|
+
| `memory_update` | Partially correct content, summary, tier, level, tags, metadata, importance, or confidence. |
|
|
91
|
+
| `memory_forget` | Permanently delete a memory. |
|
|
92
|
+
|
|
93
|
+
`memory_answer` is added dynamically only when authenticated
|
|
94
|
+
`GET /healthz?verbose=1` returns the literal boolean
|
|
95
|
+
`deps.llm.configured: true`. Missing, malformed, false, unreachable, or
|
|
96
|
+
unrouted capability evidence leaves the tool unadvertised.
|
|
97
|
+
|
|
98
|
+
The REST-backed answer tool intentionally omits MCP's `reasoning_level` because
|
|
99
|
+
the current `/v1/answer` REST request does not accept it. REST briefing also
|
|
100
|
+
does not expose the service's truncated-child count, so Pi preserves every
|
|
101
|
+
returned child rollup but does not fabricate `children_note`.
|
|
102
|
+
|
|
103
|
+
Read results include namespace/provenance evidence. For inherited or personal
|
|
104
|
+
memories, copy the returned `namespace` verbatim into get/history/update/forget;
|
|
105
|
+
do not invent namespace paths. Writes choose semantic `visibility` instead.
|
|
106
|
+
|
|
107
|
+
### Compact rendering
|
|
108
|
+
|
|
109
|
+
All explicit tools keep their complete structured JSON in the tool result sent
|
|
110
|
+
to the model and stored in the session. Their TUI renderer shows a concise
|
|
111
|
+
single line when collapsed and, with Pi's tool-expansion key (`Ctrl+O` by
|
|
112
|
+
default), a bounded human-readable view with at most eight memory/source items
|
|
113
|
+
plus kind-specific answer, acknowledgement, merge, and child-rollup details.
|
|
114
|
+
|
|
115
|
+
Automatic briefing and recall messages likewise remain persistent model
|
|
116
|
+
context while registered message renderers keep the normal transcript to one
|
|
117
|
+
line. Rendering never truncates or rewrites the model-facing payload.
|
|
118
|
+
|
|
119
|
+
## Configure
|
|
120
|
+
|
|
121
|
+
The extension has two configuration layers:
|
|
122
|
+
|
|
123
|
+
1. **Transport and identity** come from the environment of the Pi process.
|
|
124
|
+
2. **Behavior settings** resolve as **environment override → handshake server
|
|
125
|
+
setting → built-in default**. This lets one server set team defaults while a
|
|
126
|
+
local environment can override a specific knob.
|
|
127
|
+
|
|
128
|
+
### Transport and identity environment
|
|
129
|
+
|
|
130
|
+
| Environment variable | Default | Effect |
|
|
131
|
+
| ------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| `MEMINI_BASE_URL` | `http://localhost:8080` | memini REST base URL. |
|
|
133
|
+
| `MEMINI_API_KEY` | unset | Bearer token. |
|
|
134
|
+
| `MEMINI_REQUIRE_HTTPS` | off | Set to `1` to refuse a bearer token over non-loopback plaintext HTTP. |
|
|
135
|
+
| `MEMINI_HOME` | unset | Personal namespace sent as `X-Memini-Home`; unset means no personal read leg. |
|
|
136
|
+
| `MEMINI_NAMESPACE` | unset | Declared namespace fact and offline machine-local fallback; a server pin still wins. |
|
|
137
|
+
| `MEMINI_NAMESPACE_PREFIX` | unset | Prefix applied only to derived namespaces, online and in degraded fallback. |
|
|
138
|
+
| `MEMINI_AGENT` | unset | Optional per-agent namespace suffix fact. |
|
|
139
|
+
| `MEMINI_TIMEOUT_MS` | `30000` | Per-request timeout in milliseconds. |
|
|
140
|
+
| `MEMINI_FALLBACK` | on | `0`/`false` makes automatic lifecycle transport failures surface instead of degrading to warnings/no-op. |
|
|
141
|
+
|
|
142
|
+
The initial handshake sends git remote, repository root, cwd basename, and the
|
|
143
|
+
identity facts above. The server resolves pins and other server-side policy and
|
|
144
|
+
returns the authoritative namespace. The result is memoized for ten minutes;
|
|
145
|
+
setting or clearing a pin invalidates it immediately. If the handshake is
|
|
146
|
+
unreachable, Pi derives a namespace only for diagnostics and marks it degraded;
|
|
147
|
+
automatic memory traffic pauses and explicit tools refuse to route until server
|
|
148
|
+
authority is restored.
|
|
149
|
+
|
|
150
|
+
### Behavior settings used by Pi
|
|
151
|
+
|
|
152
|
+
| Environment override | Built-in default | Effect |
|
|
153
|
+
| ------------------------------------ | ---------------- | --------------------------------------------------------------------------------------------- |
|
|
154
|
+
| `MEMINI_RECALL` | on | Automatic prompt recall. |
|
|
155
|
+
| `MEMINI_CAPTURE` | on | Settled-turn capture. |
|
|
156
|
+
| `MEMINI_RECALL_LIMIT` | `3` | Maximum automatic recall hits. |
|
|
157
|
+
| `MEMINI_INJECT_RECALL_MAX_TOK` | `0` | Recall injection token ceiling; `0` is unbounded. |
|
|
158
|
+
| `MEMINI_INJECT_RECALL_MIN_SCORE` | `0` | Minimum automatic recall score. |
|
|
159
|
+
| `MEMINI_INJECT_DEDUPE` | on | Shared cross-surface suppression state. |
|
|
160
|
+
| `MEMINI_INJECT_COOLDOWN_MS` | `1800000` | Time cooldown for repeated injection; `0` disables this dimension. |
|
|
161
|
+
| `MEMINI_INJECT_COOLDOWN_PROMPTS` | `3` | Prompt cooldown; `0` disables this dimension. Both cooldowns at `0` suppress for the session. |
|
|
162
|
+
| `MEMINI_INJECT_LABELS` | empty | Comma/pipe-separated automatic bullet labels: `tier`, `confidence`, `age`. |
|
|
163
|
+
| `MEMINI_INJECT_BRIEFING_PINNED` | `5` | Startup pinned-memory cap. |
|
|
164
|
+
| `MEMINI_INJECT_BRIEFING_FACTS` | `5` | Startup durable-fact cap. |
|
|
165
|
+
| `MEMINI_INJECT_BRIEFING_PROCEDURES` | `5` | Startup procedure cap. |
|
|
166
|
+
| `MEMINI_INJECT_BRIEFING_RECENT` | `3` | Startup recent-memory cap. |
|
|
167
|
+
| `MEMINI_INJECT_BRIEFING_MAX_TOK` | `0` | Whole briefing token ceiling; `0` is unbounded. |
|
|
168
|
+
| `MEMINI_SESSION_DIGEST` | on | Pre-compaction and shutdown activity checkpoints. |
|
|
169
|
+
| `MEMINI_MIN_CAPTURE_CHARS` | `0` | Minimum settled user-text length required for capture. |
|
|
170
|
+
| `MEMINI_CAPTURE_USER_MAX_CHARS` | `1000` | Per-turn captured user-text cap; `0` is unbounded. |
|
|
171
|
+
| `MEMINI_CAPTURE_ASSISTANT_MAX_CHARS` | `3000` | Per-turn captured assistant-text cap; `0` is unbounded. |
|
|
172
|
+
|
|
173
|
+
An already injected memory stays suppressed while **either** configured
|
|
174
|
+
cooldown still holds and may return only after both lapse. Explicit read tools
|
|
175
|
+
use conservative suppression until a correction evicts the stale entry.
|
|
176
|
+
|
|
177
|
+
## Slash commands
|
|
178
|
+
|
|
179
|
+
Type commands with the leading `/` in Pi's editor:
|
|
180
|
+
|
|
181
|
+
| Command | Effect |
|
|
182
|
+
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
183
|
+
| `/memini:status` | Show effective settings and provenance, resolved namespace, connection status, read set, redacted auth, and warnings. |
|
|
184
|
+
| `/memini:namespace` | Show the current server-resolved namespace and pin provenance. |
|
|
185
|
+
| `/memini:namespace <namespace>` | Set this project's server-side namespace pin. |
|
|
186
|
+
| `/memini:namespace --clear` | Clear the server-side pin and return to automatic resolution. |
|
|
187
|
+
|
|
188
|
+
Command diagnostics are persisted as TUI-only custom entries and never enter
|
|
189
|
+
the model context, including server-authored pin notes and read-set labels.
|
|
190
|
+
|
|
191
|
+
Pins are stored by the memini server (`PUT`/`DELETE /v1/pins`) and keyed by the
|
|
192
|
+
project's git remote and/or repository root. They follow the project across
|
|
193
|
+
machines and beat `MEMINI_NAMESPACE` deliberately. Pin writes require a
|
|
194
|
+
reachable server; `MEMINI_NAMESPACE` remains the offline local override.
|
|
195
|
+
|
|
196
|
+
## Build and verify
|
|
197
|
+
|
|
198
|
+
From the package directory:
|
|
97
199
|
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
200
|
+
```sh
|
|
201
|
+
cd integrations/pi/plugin
|
|
202
|
+
npm ci
|
|
203
|
+
npm test
|
|
102
204
|
```
|
|
103
205
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
206
|
+
`npm test` is the standard verification path. It type-checks source and tests
|
|
207
|
+
against Pi 0.80.6, builds `dist/index.js`, runs bundle and helper/lifecycle/tool
|
|
208
|
+
contract tests, packs the publication artifact, installs it into a clean
|
|
209
|
+
consumer, and imports the installed ESM with only Pi-provided peer modules.
|
|
108
210
|
|
|
109
|
-
|
|
110
|
-
exported `MEMINI_NAMESPACE` is exactly the problem a pin exists to solve, so if
|
|
111
|
-
the environment won, the command would silently do nothing on the machines that
|
|
112
|
-
need it. Setting or clearing a pin takes effect on the next turn — the write
|
|
113
|
-
drops the extension's in-memory handshake memo, so there is no restart or
|
|
114
|
-
ten-minute wait.
|
|
211
|
+
Useful focused commands:
|
|
115
212
|
|
|
116
|
-
|
|
117
|
-
|
|
213
|
+
```sh
|
|
214
|
+
npm run typecheck
|
|
215
|
+
npm run build
|
|
216
|
+
npm run test:unit
|
|
217
|
+
npm run test:package
|
|
218
|
+
npm pack --dry-run
|
|
219
|
+
```
|
|
118
220
|
|
|
119
|
-
|
|
221
|
+
The package's `prepack` hook repeats typecheck and build so a direct `npm pack`
|
|
222
|
+
or publish cannot ship stale source. `@memini/client` is bundled into the
|
|
223
|
+
single extension file; `typebox`, `@earendil-works/pi-coding-agent`, and
|
|
224
|
+
`@earendil-works/pi-tui` remain host-provided peers as required for Pi packages.
|
|
225
|
+
|
|
226
|
+
Relevant cross-integration parity checks from the repository root are:
|
|
120
227
|
|
|
121
228
|
```sh
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
npm run build # esbuild bundle -> dist/index.js
|
|
125
|
-
npm test # bundle test (node --test) + pure-helper unit tests (tsx --test)
|
|
229
|
+
pnpm --filter @memini/client test
|
|
230
|
+
node --test plugin/scripts/_test.mjs
|
|
126
231
|
```
|
|
127
232
|
|
|
128
233
|
## Alternative: MCP wire
|
|
129
234
|
|
|
130
|
-
Pi can
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
(remote) or `memini mcp` (stdio). The native extension above is simpler and adds
|
|
135
|
-
the automatic recall/capture loop on top of the tools, so prefer it.
|
|
235
|
+
Pi can reach memini's `memory_*` tools through a third-party MCP extension, then
|
|
236
|
+
connect to `http://<host>:8080/mcp` or `memini mcp` (stdio). The native package
|
|
237
|
+
above is preferred because it also provides automatic recall/capture, lifecycle
|
|
238
|
+
state, capability gating, and compact rendering.
|