@hcflabs/pi-memory 0.0.0-stage → 9.3.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/LICENSE +22 -0
- package/README.md +142 -2
- package/docs/memory-architecture.html +195 -0
- package/docs/memory-architecture.svg +155 -0
- package/docs/remember-queue-flow.html +128 -0
- package/docs/remember-queue-flow.svg +120 -0
- package/extensions/memory.ts +1242 -0
- package/package.json +59 -4
- package/src/config.ts +25 -0
- package/src/store.ts +520 -0
|
@@ -0,0 +1,128 @@
|
|
|
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>How /remember waits and resumes</title>
|
|
7
|
+
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
|
|
8
|
+
<style>
|
|
9
|
+
body { margin: 0; padding: 32px; background: #f0eee9; color: #101828; font-family: 'Geist', system-ui, sans-serif; }
|
|
10
|
+
.frame { max-width: 1280px; margin: auto; }
|
|
11
|
+
h1 { font: 400 28px 'Instrument Serif', Georgia, serif; }
|
|
12
|
+
.diagram-scroll { overflow-x: auto; }
|
|
13
|
+
svg { display: block; min-width: 1280px; }
|
|
14
|
+
</style>
|
|
15
|
+
</head>
|
|
16
|
+
<body>
|
|
17
|
+
<main class="frame">
|
|
18
|
+
<h1>How /remember waits and resumes</h1>
|
|
19
|
+
<div class="diagram-scroll">
|
|
20
|
+
<!-- Timing overview: eight nodes. Review policy stays in the README and memory-architecture.svg. -->
|
|
21
|
+
<!-- Source: extensions/memory.ts: remember handler, processRemember, agent_settled, memoryTool.execute, and lifecycle handlers. -->
|
|
22
|
+
<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="remember-queue-flow-title remember-queue-flow-desc">
|
|
23
|
+
<title id="remember-queue-flow-title">The /remember request and conflict queues</title>
|
|
24
|
+
<desc id="remember-queue-flow-desc">Active responses defer conflicts and remember requests separately; after settlement, conflicts run first, then requests, with live-source checks before review, questions, or writes.</desc>
|
|
25
|
+
<defs>
|
|
26
|
+
<style>
|
|
27
|
+
.heading { fill: #101828; font: 600 20px 'Geist', sans-serif; }
|
|
28
|
+
.eyebrow { fill: #6a7282; font: 500 10px 'Geist Mono', monospace; letter-spacing: .08em; }
|
|
29
|
+
.node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
|
|
30
|
+
.queue { fill: #e6e4de; stroke: #4c5665; stroke-width: 1; }
|
|
31
|
+
.input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
|
|
32
|
+
.focal { fill: rgba(29,78,216,.08); stroke: #1d4ed8; stroke-width: 1.2; }
|
|
33
|
+
.name { fill: #101828; font: 600 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
34
|
+
.body { fill: #4c5665; font: 400 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
35
|
+
.code { fill: #4c5665; font: 400 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
36
|
+
.edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#arrow); }
|
|
37
|
+
.edge-primary { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#arrow-primary); }
|
|
38
|
+
.label-mask { fill: #f0eee9; }
|
|
39
|
+
.label { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
40
|
+
.note { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
|
|
41
|
+
</style>
|
|
42
|
+
<marker id="arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
|
|
43
|
+
<marker id="arrow-primary" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
|
|
44
|
+
</defs>
|
|
45
|
+
<rect width="1280" height="720" fill="#f0eee9"/>
|
|
46
|
+
<text class="heading" x="40" y="64">Wait for the response, then process both queues</text>
|
|
47
|
+
<text class="eyebrow" x="40" y="104">DURING AN ACTIVE RESPONSE</text>
|
|
48
|
+
<text class="eyebrow" x="344" y="160">AFTER SETTLEMENT · ONLY WHILE IDLE</text>
|
|
49
|
+
|
|
50
|
+
<!-- Queue routes and processing routes precede nodes. -->
|
|
51
|
+
<path class="edge" d="M280 180 H304 Q312 180 312 188 V224 Q312 232 320 232 H344"/>
|
|
52
|
+
<path class="edge" d="M280 332 H304 Q312 332 312 324 V288 Q312 280 320 280 H344"/>
|
|
53
|
+
<line class="edge-primary" x1="584" y1="256" x2="656" y2="256"/>
|
|
54
|
+
<path class="edge" d="M464 320 V368 Q464 376 472 376 H708 Q716 376 716 384 V440"/>
|
|
55
|
+
<line class="edge" x1="584" y1="492" x2="656" y2="492"/>
|
|
56
|
+
<line class="edge" x1="800" y1="440" x2="800" y2="320"/>
|
|
57
|
+
<line class="edge" x1="888" y1="224" x2="1008" y2="224"/>
|
|
58
|
+
<path class="edge" d="M888 288 H952 Q960 288 960 296 V464 Q960 472 968 472 H1008"/>
|
|
59
|
+
<line class="edge" x1="1120" y1="400" x2="1120" y2="296"/>
|
|
60
|
+
|
|
61
|
+
<rect class="label-mask" x="588" y="232" width="64" height="14" rx="2"/>
|
|
62
|
+
<text class="label" x="620" y="242">1 FIRST</text>
|
|
63
|
+
<rect class="label-mask" x="532" y="352" width="88" height="14" rx="2"/>
|
|
64
|
+
<text class="label" x="576" y="362">2 THEN</text>
|
|
65
|
+
<rect class="label-mask" x="808" y="380" width="72" height="14" rx="2"/>
|
|
66
|
+
<text class="label" x="844" y="390">PROPOSAL</text>
|
|
67
|
+
<rect class="label-mask" x="912" y="200" width="72" height="14" rx="2"/>
|
|
68
|
+
<text class="label" x="948" y="210">DISTINCT</text>
|
|
69
|
+
<rect class="label-mask" x="912" y="264" width="72" height="14" rx="2"/>
|
|
70
|
+
<text class="label" x="948" y="274">CONFLICT</text>
|
|
71
|
+
<rect class="label-mask" x="1128" y="336" width="104" height="14" rx="2"/>
|
|
72
|
+
<text class="label" x="1180" y="346">CHECKS PASS</text>
|
|
73
|
+
|
|
74
|
+
<rect class="queue" x="40" y="128" width="240" height="104" rx="6"/>
|
|
75
|
+
<text class="name" x="160" y="160">Conflict queue</text>
|
|
76
|
+
<text class="body" x="160" y="184">Interactive questions wait</text>
|
|
77
|
+
<text class="code" x="160" y="208">queued: true · saved: false</text>
|
|
78
|
+
|
|
79
|
+
<rect class="queue" x="40" y="280" width="240" height="104" rx="6"/>
|
|
80
|
+
<text class="name" x="160" y="312">Remember queue</text>
|
|
81
|
+
<text class="body" x="160" y="336">Trimmed requests wait</text>
|
|
82
|
+
<text class="code" x="160" y="360">/remember <instruction></text>
|
|
83
|
+
|
|
84
|
+
<rect class="focal" x="344" y="192" width="240" height="128" rx="6"/>
|
|
85
|
+
<text class="name" x="464" y="224">Response settles</text>
|
|
86
|
+
<text class="body" x="464" y="248">Conflicts first, then requests</text>
|
|
87
|
+
<text class="body" x="464" y="272">FIFO within each queue</text>
|
|
88
|
+
<text class="code" x="464" y="296">agent_settled · idle</text>
|
|
89
|
+
|
|
90
|
+
<rect class="input" x="344" y="440" width="240" height="104" rx="6"/>
|
|
91
|
+
<text class="name" x="464" y="472">Idle request</text>
|
|
92
|
+
<text class="body" x="464" y="496">Start immediately</text>
|
|
93
|
+
<text class="code" x="464" y="520">/remember <instruction></text>
|
|
94
|
+
|
|
95
|
+
<rect class="node" x="656" y="440" width="232" height="104" rx="6"/>
|
|
96
|
+
<text class="name" x="772" y="464">Read live sources; prepare</text>
|
|
97
|
+
<text class="code" x="772" y="488">pi-memory/prepareCandidate</text>
|
|
98
|
+
<text class="body" x="772" y="512">One entry and target, or decline</text>
|
|
99
|
+
<text class="body" x="772" y="532">Decline → no write</text>
|
|
100
|
+
|
|
101
|
+
<rect class="node" x="656" y="192" width="232" height="128" rx="6"/>
|
|
102
|
+
<text class="name" x="772" y="220">Read live sources; review</text>
|
|
103
|
+
<text class="code" x="772" y="244">pi-memory/reviewCandidate</text>
|
|
104
|
+
<text class="body" x="772" y="272">Queued conflicts get a new review</text>
|
|
105
|
+
<text class="body" x="772" y="296">Exact duplicates skip review</text>
|
|
106
|
+
|
|
107
|
+
<rect class="node" x="1008" y="192" width="232" height="104" rx="6"/>
|
|
108
|
+
<text class="name" x="1124" y="224">Save</text>
|
|
109
|
+
<text class="body" x="1124" y="248">Sources must stay unchanged</text>
|
|
110
|
+
<text class="body" x="1124" y="272">Deferred result: UI notification</text>
|
|
111
|
+
|
|
112
|
+
<rect class="node" x="1008" y="400" width="232" height="144" rx="6"/>
|
|
113
|
+
<text class="name" x="1124" y="428">Ask about remaining conflicts</text>
|
|
114
|
+
<text class="code" x="1124" y="452">ask_question</text>
|
|
115
|
+
<text class="body" x="1124" y="476">Approved merge or replacement:</text>
|
|
116
|
+
<text class="body" x="1124" y="496">review again before saving</text>
|
|
117
|
+
<text class="body" x="1124" y="524">Discard or blocked → no write</text>
|
|
118
|
+
|
|
119
|
+
<!-- Two lifecycle guards apply to the entire flow. -->
|
|
120
|
+
<text class="note" x="40" y="584">Cancellation, shutdown, reload, or session replacement drops both queues. Completed writes remain saved.</text>
|
|
121
|
+
<text class="note" x="40" y="612">A new response or model change during review rejects the write. Retry in the current session.</text>
|
|
122
|
+
<line x1="40" y1="640" x2="1240" y2="640" stroke="#d5d8db" stroke-width="1"/>
|
|
123
|
+
<text class="note" x="40" y="672">Queued conflicts are not saved. The agent must finish replying without retrying or asking the user itself.</text>
|
|
124
|
+
</svg>
|
|
125
|
+
</div>
|
|
126
|
+
</main>
|
|
127
|
+
</body>
|
|
128
|
+
</html>
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="remember-queue-flow-title remember-queue-flow-desc" id="remember-queue-flow-root">
|
|
3
|
+
<title id="remember-queue-flow-title">The /remember request and conflict queues</title>
|
|
4
|
+
<desc id="remember-queue-flow-desc">Active responses defer conflicts and remember requests separately; after settlement, conflicts run first, then requests, with live-source checks before review, questions, or writes.</desc>
|
|
5
|
+
<defs>
|
|
6
|
+
<style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&family=Noto+Serif:ital@0;1&family=Noto+Sans+KR:wght@400;500;600&family=Noto+Serif+KR:wght@400&family=Noto+Sans+TC:wght@400;500;600&family=Noto+Serif+TC:wght@400&display=swap');
|
|
7
|
+
#remember-queue-flow-root { color: #101828; font-family: 'Geist', system-ui, sans-serif; }
|
|
8
|
+
#remember-queue-flow-root .diagram-scroll { overflow-x: auto; }
|
|
9
|
+
#remember-queue-flow-root .heading { fill: #101828; font: 600 20px 'Geist', sans-serif; }
|
|
10
|
+
#remember-queue-flow-root .node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
|
|
11
|
+
#remember-queue-flow-root .queue { fill: #e6e4de; stroke: #4c5665; stroke-width: 1; }
|
|
12
|
+
#remember-queue-flow-root .input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
|
|
13
|
+
#remember-queue-flow-root .focal { fill: rgba(29,78,216,.08); stroke: #1d4ed8; stroke-width: 1.2; }
|
|
14
|
+
#remember-queue-flow-root .name { fill: #101828; font: 600 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
15
|
+
#remember-queue-flow-root .body { fill: #4c5665; font: 400 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
16
|
+
#remember-queue-flow-root .code { fill: #4c5665; font: 400 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
17
|
+
#remember-queue-flow-root .edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#remember-queue-flow-arrow); }
|
|
18
|
+
#remember-queue-flow-root .edge-primary { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#remember-queue-flow-arrow-primary); }
|
|
19
|
+
#remember-queue-flow-root .label-mask { fill: #f0eee9; }
|
|
20
|
+
#remember-queue-flow-root .label { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
21
|
+
#remember-queue-flow-root .note { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }</style>
|
|
22
|
+
<style>
|
|
23
|
+
.heading { fill: #101828; font: 600 20px 'Geist', sans-serif; }
|
|
24
|
+
.eyebrow { fill: #6a7282; font: 500 10px 'Geist Mono', monospace; letter-spacing: .08em; }
|
|
25
|
+
.node { fill: #ffffff; stroke: #101828; stroke-width: 1; }
|
|
26
|
+
.queue { fill: #e6e4de; stroke: #4c5665; stroke-width: 1; }
|
|
27
|
+
.input { fill: #e6e4de; stroke: #6a7282; stroke-width: 1; }
|
|
28
|
+
.focal { fill: rgba(29,78,216,.08); stroke: #1d4ed8; stroke-width: 1.2; }
|
|
29
|
+
.name { fill: #101828; font: 600 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
30
|
+
.body { fill: #4c5665; font: 400 14px 'Geist', sans-serif; text-anchor: middle; }
|
|
31
|
+
.code { fill: #4c5665; font: 400 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
32
|
+
.edge { fill: none; stroke: #4c5665; stroke-width: 1.2; marker-end: url(#remember-queue-flow-arrow); }
|
|
33
|
+
.edge-primary { fill: none; stroke: #1d4ed8; stroke-width: 1.2; marker-end: url(#remember-queue-flow-arrow-primary); }
|
|
34
|
+
.label-mask { fill: #f0eee9; }
|
|
35
|
+
.label { fill: #4c5665; font: 500 10px 'Geist Mono', monospace; text-anchor: middle; }
|
|
36
|
+
.note { fill: #4c5665; font: 400 14px 'Geist', sans-serif; }
|
|
37
|
+
</style>
|
|
38
|
+
<marker id="remember-queue-flow-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#4c5665"/></marker>
|
|
39
|
+
<marker id="remember-queue-flow-arrow-primary" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto"><polygon points="0 0,8 3,0 6" fill="#1d4ed8"/></marker>
|
|
40
|
+
</defs>
|
|
41
|
+
<rect width="1280" height="720" fill="#f0eee9"/>
|
|
42
|
+
<text class="heading" x="40" y="64">Wait for the response, then process both queues</text>
|
|
43
|
+
<text class="eyebrow" x="40" y="104">DURING AN ACTIVE RESPONSE</text>
|
|
44
|
+
<text class="eyebrow" x="344" y="160">AFTER SETTLEMENT · ONLY WHILE IDLE</text>
|
|
45
|
+
|
|
46
|
+
<!-- Queue routes and processing routes precede nodes. -->
|
|
47
|
+
<path class="edge" d="M280 180 H304 Q312 180 312 188 V224 Q312 232 320 232 H344"/>
|
|
48
|
+
<path class="edge" d="M280 332 H304 Q312 332 312 324 V288 Q312 280 320 280 H344"/>
|
|
49
|
+
<line class="edge-primary" x1="584" y1="256" x2="656" y2="256"/>
|
|
50
|
+
<path class="edge" d="M464 320 V368 Q464 376 472 376 H708 Q716 376 716 384 V440"/>
|
|
51
|
+
<line class="edge" x1="584" y1="492" x2="656" y2="492"/>
|
|
52
|
+
<line class="edge" x1="800" y1="440" x2="800" y2="320"/>
|
|
53
|
+
<line class="edge" x1="888" y1="224" x2="1008" y2="224"/>
|
|
54
|
+
<path class="edge" d="M888 288 H952 Q960 288 960 296 V464 Q960 472 968 472 H1008"/>
|
|
55
|
+
<line class="edge" x1="1120" y1="400" x2="1120" y2="296"/>
|
|
56
|
+
|
|
57
|
+
<rect class="label-mask" x="588" y="232" width="64" height="14" rx="2"/>
|
|
58
|
+
<text class="label" x="620" y="242">1 FIRST</text>
|
|
59
|
+
<rect class="label-mask" x="532" y="352" width="88" height="14" rx="2"/>
|
|
60
|
+
<text class="label" x="576" y="362">2 THEN</text>
|
|
61
|
+
<rect class="label-mask" x="808" y="380" width="72" height="14" rx="2"/>
|
|
62
|
+
<text class="label" x="844" y="390">PROPOSAL</text>
|
|
63
|
+
<rect class="label-mask" x="912" y="200" width="72" height="14" rx="2"/>
|
|
64
|
+
<text class="label" x="948" y="210">DISTINCT</text>
|
|
65
|
+
<rect class="label-mask" x="912" y="264" width="72" height="14" rx="2"/>
|
|
66
|
+
<text class="label" x="948" y="274">CONFLICT</text>
|
|
67
|
+
<rect class="label-mask" x="1128" y="336" width="104" height="14" rx="2"/>
|
|
68
|
+
<text class="label" x="1180" y="346">CHECKS PASS</text>
|
|
69
|
+
|
|
70
|
+
<rect class="queue" x="40" y="128" width="240" height="104" rx="6"/>
|
|
71
|
+
<text class="name" x="160" y="160">Conflict queue</text>
|
|
72
|
+
<text class="body" x="160" y="184">Interactive questions wait</text>
|
|
73
|
+
<text class="code" x="160" y="208">queued: true · saved: false</text>
|
|
74
|
+
|
|
75
|
+
<rect class="queue" x="40" y="280" width="240" height="104" rx="6"/>
|
|
76
|
+
<text class="name" x="160" y="312">Remember queue</text>
|
|
77
|
+
<text class="body" x="160" y="336">Trimmed requests wait</text>
|
|
78
|
+
<text class="code" x="160" y="360">/remember <instruction></text>
|
|
79
|
+
|
|
80
|
+
<rect class="focal" x="344" y="192" width="240" height="128" rx="6"/>
|
|
81
|
+
<text class="name" x="464" y="224">Response settles</text>
|
|
82
|
+
<text class="body" x="464" y="248">Conflicts first, then requests</text>
|
|
83
|
+
<text class="body" x="464" y="272">FIFO within each queue</text>
|
|
84
|
+
<text class="code" x="464" y="296">agent_settled · idle</text>
|
|
85
|
+
|
|
86
|
+
<rect class="input" x="344" y="440" width="240" height="104" rx="6"/>
|
|
87
|
+
<text class="name" x="464" y="472">Idle request</text>
|
|
88
|
+
<text class="body" x="464" y="496">Start immediately</text>
|
|
89
|
+
<text class="code" x="464" y="520">/remember <instruction></text>
|
|
90
|
+
|
|
91
|
+
<rect class="node" x="656" y="440" width="232" height="104" rx="6"/>
|
|
92
|
+
<text class="name" x="772" y="464">Read live sources; prepare</text>
|
|
93
|
+
<text class="code" x="772" y="488">pi-memory/prepareCandidate</text>
|
|
94
|
+
<text class="body" x="772" y="512">One entry and target, or decline</text>
|
|
95
|
+
<text class="body" x="772" y="532">Decline → no write</text>
|
|
96
|
+
|
|
97
|
+
<rect class="node" x="656" y="192" width="232" height="128" rx="6"/>
|
|
98
|
+
<text class="name" x="772" y="220">Read live sources; review</text>
|
|
99
|
+
<text class="code" x="772" y="244">pi-memory/reviewCandidate</text>
|
|
100
|
+
<text class="body" x="772" y="272">Queued conflicts get a new review</text>
|
|
101
|
+
<text class="body" x="772" y="296">Exact duplicates skip review</text>
|
|
102
|
+
|
|
103
|
+
<rect class="node" x="1008" y="192" width="232" height="104" rx="6"/>
|
|
104
|
+
<text class="name" x="1124" y="224">Save</text>
|
|
105
|
+
<text class="body" x="1124" y="248">Sources must stay unchanged</text>
|
|
106
|
+
<text class="body" x="1124" y="272">Deferred result: UI notification</text>
|
|
107
|
+
|
|
108
|
+
<rect class="node" x="1008" y="400" width="232" height="144" rx="6"/>
|
|
109
|
+
<text class="name" x="1124" y="428">Ask about remaining conflicts</text>
|
|
110
|
+
<text class="code" x="1124" y="452">ask_question</text>
|
|
111
|
+
<text class="body" x="1124" y="476">Approved merge or replacement:</text>
|
|
112
|
+
<text class="body" x="1124" y="496">review again before saving</text>
|
|
113
|
+
<text class="body" x="1124" y="524">Discard or blocked → no write</text>
|
|
114
|
+
|
|
115
|
+
<!-- Two lifecycle guards apply to the entire flow. -->
|
|
116
|
+
<text class="note" x="40" y="584">Cancellation, shutdown, reload, or session replacement drops both queues. Completed writes remain saved.</text>
|
|
117
|
+
<text class="note" x="40" y="612">A new response or model change during review rejects the write. Retry in the current session.</text>
|
|
118
|
+
<line x1="40" y1="640" x2="1240" y2="640" stroke="#d5d8db" stroke-width="1"/>
|
|
119
|
+
<text class="note" x="40" y="672">Queued conflicts are not saved. The agent must finish replying without retrying or asking the user itself.</text>
|
|
120
|
+
</svg>
|