@codemem/pi-extension 0.46.2 → 0.47.0-beta.2

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 (2) hide show
  1. package/README.md +15 -11
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -6,10 +6,10 @@ Pi coding-agent extension for [codemem](https://github.com/kunickiaj/codemem): s
6
6
 
7
7
  ```bash
8
8
  npm i -g codemem
9
- codemem setup
9
+ codemem setup --pi-only
10
10
  ```
11
11
 
12
- `codemem setup` auto-detects pi and appends `npm:@codemem/pi-extension@<version>` to `~/.pi/agent/settings.json` `packages`. Useful flags:
12
+ Restart Pi after setup. `codemem setup --pi-only` configures only Pi. A fresh setup adds `npm:@codemem/pi-extension@<version>` to `settings.json` `packages` (`PI_CODING_AGENT_DIR` when set, otherwise `~/.pi/agent`); an existing configured dev path may be retained. Useful flags:
13
13
 
14
14
  | Flag | Purpose |
15
15
  | --- | --- |
@@ -31,27 +31,30 @@ Build first so `dist/index.js` exists (`pnpm --filter @codemem/pi-extension buil
31
31
 
32
32
  ## What it does
33
33
 
34
- - **Ingest** — captures pi session events (`session_start`/`session_shutdown`, user/assistant messages, tool calls/results) into codemem with `source: "pi"` via `POST /api/pi-hooks` (compat alias over the canonical ingest envelope), falling back to `codemem pi-hook-ingest` (spool when offline).
34
+ - **Ingest** — ordinary session events (`session_start`, user/assistant messages, tool calls/results) prefer `POST /api/pi-hooks` (`source: "pi"`), with `codemem pi-hook-ingest` CLI fallback (spool on failure). Boundary events (`session_before_compact`, `session_shutdown`) always attempt the CLI path so a flush can run; failure is fail-open.
35
35
  - **Injection** — on pi's `context` event, appends a `## codemem memories` block to the latest user message of the **request copy** (never the system prompt, never the saved session). Older user messages replay the exact bytes already injected for them, and a new pack is fetched only for the latest undecided message, so the provider's prefix cache stays stable. Already-shown items are cut from new packs when the pack response carries renderer spans. A contract-valid HTTP or `pack --json` response, including a zero-item pack, ends that fetch; `{}` and error-shaped bodies fall through. Those span-bearing successes log `inject.pack.ok source=pi` to the plugin log, the same line `pi-hook-inject` writes when it is the fallback. Decisions live in memory: a restart fetches again.
36
+ - **File context** — after a successful built-in `read`, related memories may be appended to that tool result. Failed reads and other tools are skipped.
36
37
  - **Tools** — registers the 14 `memory_*` tools natively (HTTP preferred, CLI fallback). Every HTTP operation first proves the viewer is target-aware (`GET /api/prompt-pack-profile` must report this process's `db_path` + `identity_target`) and re-sends the target on the query, so a foreign or stale older viewer on the port is never trusted (409 or unproven → targeted CLI path). Non-idempotent `memory_remember` does NOT CLI-replay on ambiguous HTTP failures (timeout/5xx/reset after send). No `pi-mcp-adapter` needed. Skipped when `pi.tools_mode` is `mcp-adapter`.
37
- - **Compaction** — `session_before_compact` still only flushes extraction and never returns a custom summary. The next context skips a new pack fetch only after `session_compact` with `willRetry`, which is Pi's automatic overflow resume. Manual, threshold, cancelled, and failed compactions do not skip that fetch, and a later user message clears a skip that was not the immediate resume.
38
- - **Fork/resume** — re-keys stream identity on every `session_start`; durable cursors via `pi.appendEntry`.
38
+ - **Compaction** — `session_before_compact` attempts a flush only and never returns a custom summary. `session_compact` skips one new fetch only when `willRetry` is set and `reason` is not `manual`. Failed compaction, `agent_settled`, manual compaction, and a later user message clear that skip. A threshold compact skips only if that same guard matches.
39
+ - **Fork/resume** — re-keys stream identity on every `session_start`. Ingest cursor metadata persists via `pi.appendEntry` (`codemem.cursor`). Recall decisions stay in memory and are cleared on `session_start`; a restart refetches.
39
40
  - **Cross-agent** — one shared, project-scoped store. Memories from OpenCode/Claude/Codex inject into pi and the reverse.
40
41
  - **Dashboard** — pi rows appear in the source-agnostic feed/sessions/projects tabs with no extra setup.
41
42
 
43
+ Tool purposes and troubleshooting: [Pi extension](https://github.com/kunickiaj/codemem/blob/main/docs/plugin-reference.md#pi-extension).
44
+
42
45
  ## Observer derivation (v1)
43
46
 
44
- Setup can fill unset `observer_*` keys from pi's API-key providers (cheap-model-first). Credentials stay in memory only and are never written to codemem config. OAuth-only installs get an explicit `unconfigured (oauth-only)` status — never a silent failure. Set `observer_provider` / `observer_model` explicitly when needed. Explicit `observer_*` config/env always wins.
47
+ Setup can fill unset `observer_*` keys from pi's API-key providers (cheap-model-first). Credentials stay in memory only and are never written to codemem config. `unconfigured (oauth-only)` is an auto-derivation status when only OAuth credentials are available, not the state of every observer connection. Configure observer credentials or the connection separately, with provider or model overrides as needed ([observer auth](https://github.com/kunickiaj/codemem/blob/main/docs/user-guide.md#observer-auth-configuration)). Explicit `observer_*` config/env always wins.
45
48
 
46
49
  ## Configuration
47
50
 
48
- Read from `~/.config/codemem/config.json` under the `pi` object, with `CODEMEM_PI_*` env overrides.
51
+ Read from `CODEMEM_CONFIG` when set, otherwise `$XDG_CONFIG_HOME/codemem` or `~/.config/codemem`, using an existing `config.json` then `config.jsonc`. Pi keys live under the `pi` object, with `CODEMEM_PI_*` env overrides.
49
52
 
50
53
  | Key / env | Default | Meaning |
51
54
  | --- | --- | --- |
52
- | `pi.tools_mode` / `CODEMEM_PI_TOOLS_MODE` | `native` | `native` registers tools here; `mcp-adapter` skips native registration (use pi-mcp-adapter + `codemem mcp`) |
55
+ | `pi.tools_mode` / `CODEMEM_PI_TOOLS_MODE` | `native` | `native` registers tools here; `mcp-adapter` skips native registration; configure MCP separately |
53
56
  | `pi.inject_prompts` / `CODEMEM_PI_INJECT_PROMPTS` | `true` | Attach the memory pack to the latest user message on each model request |
54
- | `pi.file_context` / `CODEMEM_PI_FILE_CONTEXT` | `true` | Attach file-related memories when pi `read`s a tracked file |
57
+ | `pi.file_context` / `CODEMEM_PI_FILE_CONTEXT` | `true` | Append related memories to successful built-in read results when available |
55
58
 
56
59
  Shared viewer / inject knobs (same as other clients):
57
60
 
@@ -66,6 +69,7 @@ Shared viewer / inject knobs (same as other clients):
66
69
  | `CODEMEM_INJECT_TOKEN_BUDGET` | `800` | Pack token budget |
67
70
  | `CODEMEM_INJECT_MAX_CHARS` | `16000` | Max injection block chars |
68
71
  | `CODEMEM_INJECT_RETAINED_TOKEN_BUDGET` | uncapped | Optional approximate token ceiling for blocks already injected in the session (estimated as `ceil(chars / 4)`). Unset, zero, negative, and invalid values mean no cap; when enabled, a full ceiling attaches nothing new, fetches nothing, and never removes or truncates blocks already attached |
72
+ | `CODEMEM_PI_HOOK_HTTP_TIMEOUT_MS` | `5000` | Ingest and native-tool HTTP timeout (ms). Does not set the pack-fetch timeout |
69
73
 
70
74
  Example config:
71
75
 
@@ -81,11 +85,11 @@ Example config:
81
85
 
82
86
  ## Lifecycle
83
87
 
84
- Per pi extension rules: the factory only wires handlers. Viewer auto-start and other session resources begin on `session_start` and clean up idempotently on `session_shutdown`. Session state is re-keyed from `ctx.sessionManager.getSessionId()` on every `session_start`; durable ingest cursors persist via `pi.appendEntry`.
88
+ Per pi extension rules: the factory only wires handlers. Viewer auto-start and other session resources begin on `session_start` and clean up idempotently on `session_shutdown`. Session state is re-keyed from `ctx.sessionManager.getSessionId()` on every `session_start`; durable ingest cursors persist via `pi.appendEntry` (`codemem.cursor`). Recall decisions are not session entries.
85
89
 
86
90
  ## Peer dependencies
87
91
 
88
- - `@earendil-works/pi-coding-agent` (extension host)
92
+ - `@earendil-works/pi-coding-agent` `>=0.84.1 <1` (declared host peer; this package does not declare Pi 1 support)
89
93
  - `typebox` (tool parameter schemas)
90
94
 
91
95
  No `@codemem/core` or native modules load inside the pi process.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codemem/pi-extension",
3
- "version": "0.46.2",
3
+ "version": "0.47.0-beta.2",
4
4
  "description": "CodeMem extension for the pi coding agent — ingest, injection, and native memory tools",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -22,7 +22,7 @@
22
22
  "typebox": "*"
23
23
  },
24
24
  "devDependencies": {
25
- "@codemem/core": "^0.46.2",
25
+ "@codemem/core": "^0.47.0-beta.2",
26
26
  "@earendil-works/pi-coding-agent": "^0.84.1",
27
27
  "@types/node": "^24.12.4",
28
28
  "typebox": "^1.3.7",