pi-session-memory 0.4.0 → 0.6.0
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 +31 -184
- package/extensions/index.ts +67 -291
- package/package.json +5 -3
- package/src/backfill.ts +16 -4
- package/src/db.ts +33 -336
- package/src/fetch-session.ts +8 -0
- package/src/helper.ts +21 -41
- package/src/retriever.ts +25 -289
- package/src/writer.ts +5 -2
package/README.md
CHANGED
|
@@ -1,204 +1,51 @@
|
|
|
1
1
|
# pi-session-memory
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://pi.dev/packages)
|
|
3
|
+
A local-first Pi extension for **on-demand cross-session transcript search** across Pi, Claude Code, and Codex, plus native project-session migration to Pi `/resume` sessions.
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
## What it does
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
- Indexes local Pi, Claude Code, and Codex JSONL transcript turns in local SQLite.
|
|
8
|
+
- Provides `recall_memory` for literal raw-history search that returns every match.
|
|
9
|
+
- Provides `fetch_session` for read-only expansion of the smallest useful transcript range.
|
|
10
|
+
- Synchronizes changed history at Pi session start; `/memory-backfill` performs an explicit full rescan.
|
|
11
|
+
- Migrates current-project Claude Code or Codex sessions into separate native Pi sessions.
|
|
9
12
|
|
|
10
|
-
|
|
11
|
-
- Automatically imports only new or changed Pi, Claude Code, and Codex session files when Pi starts.
|
|
12
|
-
- Supports a forced full SQLite history rescan with `/memory-backfill`.
|
|
13
|
-
- Converts current-project Codex or Claude Code sessions into separate native Pi sessions, ready to select through `/resume`.
|
|
14
|
-
- Exposes `recall_memory`, allowing Pi to retrieve relevant prior discussions when users explicitly refer to earlier work.
|
|
15
|
-
- Uses stable native user-message IDs and `INSERT OR IGNORE`, making live persistence and backfill idempotent.
|
|
16
|
-
- Searches literal substrings with escaped SQLite `LIKE` patterns, including technical terms containing `%`, `_`, or `\\`.
|
|
17
|
-
- Ranks results by literal relevance and recency, boosts an explicitly scoped project, and limits results to two turns per session for diversity.
|
|
18
|
-
- Supports explicit durable memories, which remain after their source transcript turns are deleted.
|
|
19
|
-
- Suppresses a raw turn from recall when an active durable memory contains the same unchanged pinned source evidence; other turns in that session remain eligible.
|
|
20
|
-
- Associates recalled durable memories with later source-session activity and newer entity-relevant evidence from the same or another session, so users can explicitly compare, confirm, or supersede them without silent updates.
|
|
21
|
-
- Includes status, direct search, and permanent deletion commands so users can inspect and control local memory.
|
|
22
|
-
- Uses only Node.js built-ins and SQLite (`node:sqlite`); no external runtime dependencies.
|
|
13
|
+
Search results are derived from stored source transcripts only and are never automatically injected into model context. Put project rules and preferences in `AGENTS.md`.
|
|
23
14
|
|
|
24
|
-
##
|
|
15
|
+
## Commands
|
|
25
16
|
|
|
26
|
-
|
|
27
|
-
pi install npm:pi-session-memory
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
This unpinned source can receive package-update checks at Pi startup. After a new release, update it explicitly with:
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
pi update npm:pi-session-memory
|
|
34
|
-
# or update every unpinned Pi extension
|
|
35
|
-
pi update --extensions
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
Restart Pi after the update to load the new extension code.
|
|
39
|
-
|
|
40
|
-
To try the latest package without installing it permanently:
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
pi -e npm:pi-session-memory
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
To intentionally pin a known version (which `pi update --extensions` skips), add its version explicitly:
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
pi install npm:pi-session-memory@0.4.0
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Usage
|
|
53
|
-
|
|
54
|
-
### Import existing history
|
|
55
|
-
|
|
56
|
-
At Pi startup, the extension automatically scans the three source roots. It compares
|
|
57
|
-
per-file size and modification time to saved sync state; only new or changed JSONL
|
|
58
|
-
files are read and hashed with SHA-256 before import. Unchanged files are skipped.
|
|
59
|
-
|
|
60
|
-
Use this command when you intentionally want to force a full rescan of every
|
|
61
|
-
historical JSONL file:
|
|
62
|
-
|
|
63
|
-
```text
|
|
64
|
-
/memory-backfill
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
The command imports eligible user/assistant exchanges from:
|
|
68
|
-
|
|
69
|
-
| Source | Session location |
|
|
17
|
+
| Command | Description |
|
|
70
18
|
| --- | --- |
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
Use a migration command only when you want to continue prior work as a real Pi session rather than search it as memory:
|
|
78
|
-
|
|
79
|
-
```text
|
|
80
|
-
/project-claude-session-migration # Claude Code → Pi
|
|
81
|
-
/project-session-migration # Codex → Pi
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
Each command selects only source JSONL files whose recorded `cwd` exactly equals the current project, then creates one independent Pi v3 session JSONL under Pi's normal session directory. Entries are named `Migrated from Claude Code: <session-id>` or `Migrated from Codex: <session-id>`.
|
|
85
|
-
|
|
86
|
-
After the command completes, run:
|
|
87
|
-
|
|
88
|
-
```text
|
|
89
|
-
/resume
|
|
90
|
-
```
|
|
19
|
+
| `/pi-session-memory-helper` | Show cross-session search and migration help. |
|
|
20
|
+
| `/memory-status` | Show locally indexed session and turn totals. |
|
|
21
|
+
| `/memory-search <query>` | Search locally indexed raw transcript history. |
|
|
22
|
+
| `/memory-backfill` | Explicitly rescan historical Pi, Claude Code, and Codex JSONL. |
|
|
23
|
+
| `/project-session-migration` | Convert current-project Codex sessions for `/resume`. |
|
|
24
|
+
| `/project-claude-session-migration` | Convert current-project Claude Code sessions for `/resume`. |
|
|
91
25
|
|
|
92
|
-
|
|
26
|
+
## Agent tools
|
|
93
27
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
### Recall prior work
|
|
103
|
-
|
|
104
|
-
The extension instructs Pi to call `recall_memory` when a user explicitly asks about a previous discussion, for example:
|
|
105
|
-
|
|
106
|
-
```text
|
|
107
|
-
What did we decide about LangGraph last time?
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
`recall_memory` is the discovery step: it searches and ranks the complete active durable-memory and raw-turn match set using 2–8 high-signal literal entities. Entities are OR alternatives, so a result may match any entity; matching more entities ranks higher. Pi must not send the complete user request or generic conversational terms such as "问题", "开发", "有哪些", or "help". Where useful, it includes Chinese/English equivalents, aliases, or abbreviations—for example `["bug", "缺陷", "错误", "fix", "修复"]`. Exact project-directory, source, and time-window filters remain strict scope constraints. Each tool response deliberately renders five results and reports `totalResults` and `nextOffset`; when more candidates are needed, Pi repeats the exact same entities and scope filters with that explicit offset. This pages model context without silently limiting the local search. Raw transcript candidates contain a short excerpt plus a session ID and turn index, rather than the entire turn context. When surrounding conversation is needed to answer accurately, Pi calls `fetch_session` with that session ID and the smallest useful turn-index range. When an initial literal search is empty, Pi may make up to two additional local searches using distinct entities selected from reasoned alternatives—such as abbreviations, expansions, aliases, translations, or likely task wording—while retaining the original scope filters.
|
|
111
|
-
|
|
112
|
-
When recall returns a durable memory, Pi is instructed to naturally communicate a relevant remembered conclusion and provenance when useful. It reports later activity in the memory's source session separately from newer entity-relevant evidence to compare; that evidence can come from the original session or another newer session. Pi compares the old memory with the evidence as a possible confirmation, supplement, conflict, or replacement, then asks whether you want to keep, confirm, or replace it. It never claims a memory was updated or superseded without your explicit choice.
|
|
113
|
-
|
|
114
|
-
### Inspect and control memory
|
|
115
|
-
|
|
116
|
-
Recall and freshness explanations are automatic model behavior. The commands below remain deliberate user-control actions for inspecting or changing stored memory; they are not required for normal recalled answers.
|
|
117
|
-
|
|
118
|
-
```text
|
|
119
|
-
/remember Keep SQLite writes local only
|
|
120
|
-
/memory-pin pi:<session-id>:<user-message-id>
|
|
121
|
-
/memory-list [decision]
|
|
122
|
-
/memory-confirm <memory-id>
|
|
123
|
-
/memory-supersede <old-memory-id> <new-memory-id>
|
|
124
|
-
/memory-history <memory-id>
|
|
125
|
-
/memory-forget <memory-id>
|
|
126
|
-
/memory-delete-turn pi:<session-id>:<user-message-id>
|
|
127
|
-
/memory-status
|
|
128
|
-
/memory-search SQLite migration
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
`fetch_session` is an agent tool, not a user command: Pi invokes it selectively after `recall_memory` when it needs additional context from a specific discovered session.
|
|
132
|
-
|
|
133
|
-
- `/remember <text>` saves an explicit durable `fact` scoped to the current project.
|
|
134
|
-
- `/memory-pin <turn-id>` promotes a historical turn to a durable fact and records its source session, source turn ID, and a hash of the pinned evidence.
|
|
135
|
-
- `/memory-list [kind]` displays durable memories, optionally limited to `preference`, `decision`, `fact`, `project_state`, `task`, or `lesson`.
|
|
136
|
-
- Recall distinguishes later activity in a memory's source session from newer entity-relevant evidence to compare. That evidence may come from the original session or another newer session; it is a review signal, not an automatic update.
|
|
137
|
-
- `/memory-confirm <memory-id>` records that an active memory remains current by updating `last_confirmed_at`.
|
|
138
|
-
- `/memory-supersede <old-memory-id> <new-memory-id>` explicitly replaces an active memory while retaining the old record for history; superseded memories are excluded from normal recall.
|
|
139
|
-
- `/memory-history <memory-id>` displays the complete oldest-to-newest supersession chain.
|
|
140
|
-
- `/memory-forget <memory-id>` permanently deletes a durable memory without deleting its source transcript.
|
|
141
|
-
- `/memory-delete-turn <turn-id>` permanently deletes one raw turn; its session is also removed if it has no turns left.
|
|
142
|
-
- `/memory-status` reports turn and session totals, per-source distribution, and newest memory time.
|
|
143
|
-
- `/memory-search <query>` previews the same local literal retrieval used by the agent.
|
|
144
|
-
|
|
145
|
-
## How it works
|
|
146
|
-
|
|
147
|
-
```text
|
|
148
|
-
Pi / Claude Code / Codex history ──► incremental source sync ──► SQLite memory.db
|
|
149
|
-
▲
|
|
150
|
-
│
|
|
151
|
-
recall_memory
|
|
152
|
-
|
|
153
|
-
Current-project Claude Code JSONL ──► /project-claude-session-migration ─┐
|
|
154
|
-
Current-project Codex JSONL ────────► /project-session-migration ───────┼──► native Pi session JSONL ──► /resume
|
|
155
|
-
┘
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
After a Pi agent run settles, the extension captures the latest user message and the subsequent assistant replies/tool names from the active session branch. Historical imports normalize each supported source into the same session/turn schema.
|
|
28
|
+
| Tool | Use when |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `recall_memory` | The user explicitly asks about a prior discussion, or agrees to history search. Use 2–8 specific literal entities. |
|
|
31
|
+
| `fetch_session` | A recall excerpt lacks needed context. Fetch the smallest useful range. It is read-only. |
|
|
32
|
+
| `get_memory_stats` | The user asks how much local history is indexed. |
|
|
33
|
+
| `backfill_memory` | The user explicitly asks to import, backfill, or rescan history. |
|
|
34
|
+
| `migrate_codex_project_sessions` | The user wants to continue current-project Codex work through `/resume`. |
|
|
35
|
+
| `migrate_claude_project_sessions` | The user wants to continue current-project Claude Code work through `/resume`. |
|
|
159
36
|
|
|
160
|
-
|
|
37
|
+
## Flow
|
|
161
38
|
|
|
162
39
|
```text
|
|
163
|
-
|
|
40
|
+
session_start -> syncChangedHistory() -> SQLite raw transcript index
|
|
41
|
+
recall_memory -> matching raw transcript turns -> fetch_session (optional, read-only)
|
|
42
|
+
project migration command/tool -> native Pi session JSONL -> /resume
|
|
164
43
|
```
|
|
165
44
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
Conversation data is stored and queried locally. This package does not add a remote storage service or transmit conversation history on its own. Review the source and your model provider's configuration before using it with sensitive conversations.
|
|
169
|
-
|
|
170
|
-
## Release notes
|
|
171
|
-
|
|
172
|
-
| Version | Highlights |
|
|
173
|
-
| --- | --- |
|
|
174
|
-
| `0.4.0` | Adds native current-project Claude Code-to-Pi session migration through `/project-claude-session-migration` and `migrate_claude_project_sessions`. Claude Code and Codex now share deterministic, source-namespaced, idempotent Pi v3 session output; SQLite data and schema remain compatible, so no database migration is required. |
|
|
175
|
-
| `0.3.1` | Makes `recall_memory` entity-only: 2–8 high-signal literal entities are OR alternatives, results matching more entities rank higher, and output distinguishes search entities from strict scope filters. Existing SQLite data and schema remain compatible; no migration is required. |
|
|
176
|
-
| `0.3.0` | Replaces source-session-only freshness hints with provenance-linked evidence comparison across newer same-session and cross-session turns. This changes recall output and `freshness_candidate` semantics, but keeps SQLite data and explicit user-controlled memory mutation compatible; no migration is required. |
|
|
177
|
-
| `0.2.1` | Pages `recall_memory` results in explicit five-result `offset` windows while still evaluating the complete local match set; npm publishing now uses a runtime-file allowlist. |
|
|
178
|
-
| `0.2.0` | Added cross-client SQLite recall and durable-memory controls, plus native current-project Codex-to-Pi session migration for `/resume`. |
|
|
179
|
-
| `0.1.4` | Automatically syncs new or changed Pi, Claude Code, and Codex history when Pi starts; `/memory-backfill` forces a full rescan. |
|
|
180
|
-
| `0.1.3` | Improved package documentation and installation guidance. |
|
|
181
|
-
| `0.1.2` | Added the MIT license. |
|
|
182
|
-
| `0.1.1` | Added repository and package metadata for public distribution. |
|
|
183
|
-
| `0.1.0` | Initial release: local SQLite memory, Pi live persistence, historical import, and `recall_memory` retrieval. |
|
|
184
|
-
|
|
185
|
-
## Release compatibility review
|
|
186
|
-
|
|
187
|
-
Before every significant release, review these compatibility surfaces and record any migration or versioning decision. In this project, a breaking change means an updated extension conflicts with a user's existing SQLite table structure and errors after upgrade; changes to agent tool inputs or external direct callers are not breaking changes under this definition:
|
|
188
|
-
|
|
189
|
-
1. **Install/package:** package name, Pi manifest, runtime dependencies, and published file allowlist.
|
|
190
|
-
2. **Persistent data:** SQLite schema/migrations, JSONL-import compatibility, and any data rewrite.
|
|
191
|
-
3. **Agent tools and commands:** tool names, input schemas, result/details contracts, and slash commands.
|
|
192
|
-
4. **Retrieval and agent behavior:** ranking, pagination, freshness/evidence semantics, prompt policy, and automatic side effects.
|
|
193
|
-
5. **Public TypeScript/module API:** exported types/functions and required result fields.
|
|
194
|
-
6. **Extension loadability:** run `npm test`, which imports `extensions/index.ts`; Markdown inline-code backticks inside a template-literal description must be escaped as `\`` so Pi can parse and start the extension.
|
|
195
|
-
|
|
196
|
-
The `0.4.0` review found no SQLite breaking change: Claude Code native-session migration adds commands, an agent tool, and Pi session-file output only. It does not alter tables, migrations, or stored data, so users can upgrade without a database error or migration. It is therefore released as a minor version because it adds a backward-compatible user capability.
|
|
45
|
+
History remains on the local machine, by default in `~/.pi/agent/memory.db`. Deleting that database removes only the index; restarting Pi rebuilds it from local source JSONL files.
|
|
197
46
|
|
|
198
47
|
## Development
|
|
199
48
|
|
|
200
49
|
```bash
|
|
201
|
-
npm test
|
|
50
|
+
npm test # core database, raw recall, importer, and migration regression suite
|
|
202
51
|
```
|
|
203
|
-
|
|
204
|
-
The test suite imports `extensions/index.ts` in addition to exercising core behavior. This catches extension-load syntax errors, including unescaped Markdown backticks inside template-literal tool descriptions.
|