eagle-mem 4.9.6 → 4.9.8
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 -4
- package/architecture.html +1791 -0
- package/bin/eagle-mem +1 -0
- package/db/migrate.sh +13 -2
- package/docs/visible-surface-ux-contract.md +53 -0
- package/hooks/post-tool-use.sh +2 -2
- package/hooks/pre-tool-use.sh +6 -6
- package/hooks/session-start.sh +216 -9
- package/hooks/user-prompt-submit.sh +72 -15
- package/lib/common.sh +485 -35
- package/lib/db-mirrors.sh +9 -18
- package/lib/db-sessions.sh +22 -15
- package/lib/db-summaries.sh +19 -7
- package/lib/hooks-posttool.sh +44 -10
- package/lib/updater.sh +12 -0
- package/package.json +4 -2
- package/scripts/doctor.sh +262 -0
- package/scripts/feature.sh +37 -11
- package/scripts/health.sh +10 -7
- package/scripts/help.sh +1 -0
- package/scripts/install.sh +9 -3
- package/scripts/memories.sh +258 -65
- package/scripts/orchestrate.sh +2 -2
- package/scripts/search.sh +240 -56
- package/scripts/statusline-em.sh +130 -26
- package/scripts/uninstall.sh +67 -0
- package/scripts/update.sh +8 -1
|
@@ -0,0 +1,1791 @@
|
|
|
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>Eagle Mem Architecture Tutorial</title>
|
|
7
|
+
<style>
|
|
8
|
+
:root {
|
|
9
|
+
--ink: #111111;
|
|
10
|
+
--paper: #f7f7f2;
|
|
11
|
+
--white: #ffffff;
|
|
12
|
+
--muted: #5f6368;
|
|
13
|
+
--line: #111111;
|
|
14
|
+
--soft: #e7e7df;
|
|
15
|
+
--cyan: #00bfd8;
|
|
16
|
+
--green: #18a058;
|
|
17
|
+
--yellow: #d6a300;
|
|
18
|
+
--red: #cf3d32;
|
|
19
|
+
--code: #f0f0e8;
|
|
20
|
+
--shadow: 8px 8px 0 #111111;
|
|
21
|
+
--mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
|
|
22
|
+
--sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
* {
|
|
26
|
+
box-sizing: border-box;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
html {
|
|
30
|
+
scroll-behavior: smooth;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
body {
|
|
34
|
+
margin: 0;
|
|
35
|
+
color: var(--ink);
|
|
36
|
+
background: var(--paper);
|
|
37
|
+
font-family: var(--sans);
|
|
38
|
+
font-size: 16px;
|
|
39
|
+
line-height: 1.6;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
a {
|
|
43
|
+
color: inherit;
|
|
44
|
+
text-decoration-thickness: 2px;
|
|
45
|
+
text-underline-offset: 3px;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
code,
|
|
49
|
+
pre,
|
|
50
|
+
kbd {
|
|
51
|
+
font-family: var(--mono);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
code {
|
|
55
|
+
padding: 0.1rem 0.28rem;
|
|
56
|
+
background: var(--code);
|
|
57
|
+
border: 1px solid var(--line);
|
|
58
|
+
font-size: 0.92em;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
pre {
|
|
62
|
+
overflow-x: auto;
|
|
63
|
+
padding: 18px;
|
|
64
|
+
margin: 20px 0;
|
|
65
|
+
background: var(--ink);
|
|
66
|
+
color: var(--white);
|
|
67
|
+
border: 3px solid var(--line);
|
|
68
|
+
box-shadow: var(--shadow);
|
|
69
|
+
font-size: 0.9rem;
|
|
70
|
+
line-height: 1.5;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
pre code {
|
|
74
|
+
padding: 0;
|
|
75
|
+
color: inherit;
|
|
76
|
+
background: transparent;
|
|
77
|
+
border: 0;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
table {
|
|
81
|
+
width: 100%;
|
|
82
|
+
border-collapse: collapse;
|
|
83
|
+
margin: 24px 0;
|
|
84
|
+
background: var(--white);
|
|
85
|
+
border: 3px solid var(--line);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
th,
|
|
89
|
+
td {
|
|
90
|
+
padding: 12px 14px;
|
|
91
|
+
vertical-align: top;
|
|
92
|
+
border: 2px solid var(--line);
|
|
93
|
+
text-align: left;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
th {
|
|
97
|
+
font-family: var(--mono);
|
|
98
|
+
font-size: 0.78rem;
|
|
99
|
+
text-transform: uppercase;
|
|
100
|
+
letter-spacing: 0.05em;
|
|
101
|
+
background: var(--ink);
|
|
102
|
+
color: var(--white);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
td {
|
|
106
|
+
background: var(--white);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
ul,
|
|
110
|
+
ol {
|
|
111
|
+
padding-left: 1.4rem;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
li + li {
|
|
115
|
+
margin-top: 0.45rem;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
.skip-link {
|
|
119
|
+
position: absolute;
|
|
120
|
+
left: 16px;
|
|
121
|
+
top: -80px;
|
|
122
|
+
z-index: 20;
|
|
123
|
+
padding: 10px 14px;
|
|
124
|
+
background: var(--cyan);
|
|
125
|
+
border: 3px solid var(--line);
|
|
126
|
+
color: var(--ink);
|
|
127
|
+
font-family: var(--mono);
|
|
128
|
+
font-weight: 700;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
.skip-link:focus {
|
|
132
|
+
top: 16px;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
.layout {
|
|
136
|
+
display: grid;
|
|
137
|
+
grid-template-columns: 310px minmax(0, 1fr);
|
|
138
|
+
min-height: 100vh;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
.sidebar {
|
|
142
|
+
position: sticky;
|
|
143
|
+
top: 0;
|
|
144
|
+
height: 100vh;
|
|
145
|
+
overflow-y: auto;
|
|
146
|
+
padding: 28px 24px;
|
|
147
|
+
background: var(--white);
|
|
148
|
+
border-right: 4px solid var(--line);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
.brand {
|
|
152
|
+
padding-bottom: 22px;
|
|
153
|
+
margin-bottom: 22px;
|
|
154
|
+
border-bottom: 4px solid var(--line);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
.brand-label {
|
|
158
|
+
display: inline-block;
|
|
159
|
+
padding: 4px 8px;
|
|
160
|
+
margin-bottom: 12px;
|
|
161
|
+
font-family: var(--mono);
|
|
162
|
+
font-size: 0.72rem;
|
|
163
|
+
font-weight: 800;
|
|
164
|
+
text-transform: uppercase;
|
|
165
|
+
letter-spacing: 0.08em;
|
|
166
|
+
background: var(--cyan);
|
|
167
|
+
border: 2px solid var(--line);
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
.brand h1 {
|
|
171
|
+
margin: 0 0 10px;
|
|
172
|
+
font-family: var(--mono);
|
|
173
|
+
font-size: 1.38rem;
|
|
174
|
+
line-height: 1.18;
|
|
175
|
+
letter-spacing: 0;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
.brand p {
|
|
179
|
+
margin: 0;
|
|
180
|
+
color: var(--muted);
|
|
181
|
+
font-size: 0.92rem;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
.nav-title {
|
|
185
|
+
margin: 20px 0 8px;
|
|
186
|
+
font-family: var(--mono);
|
|
187
|
+
font-size: 0.72rem;
|
|
188
|
+
font-weight: 800;
|
|
189
|
+
text-transform: uppercase;
|
|
190
|
+
letter-spacing: 0.1em;
|
|
191
|
+
color: var(--muted);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
.nav-list {
|
|
195
|
+
padding: 0;
|
|
196
|
+
margin: 0;
|
|
197
|
+
list-style: none;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
.nav-list a {
|
|
201
|
+
display: block;
|
|
202
|
+
padding: 8px 9px;
|
|
203
|
+
margin-bottom: 4px;
|
|
204
|
+
border: 2px solid transparent;
|
|
205
|
+
font-family: var(--mono);
|
|
206
|
+
font-size: 0.82rem;
|
|
207
|
+
line-height: 1.35;
|
|
208
|
+
text-decoration: none;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
.nav-list a:hover,
|
|
212
|
+
.nav-list a:focus-visible {
|
|
213
|
+
border-color: var(--line);
|
|
214
|
+
background: var(--soft);
|
|
215
|
+
outline: none;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
main {
|
|
219
|
+
min-width: 0;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
.hero,
|
|
223
|
+
.section {
|
|
224
|
+
min-height: 100vh;
|
|
225
|
+
padding: 72px clamp(28px, 6vw, 88px);
|
|
226
|
+
border-bottom: 4px solid var(--line);
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
.hero {
|
|
230
|
+
display: grid;
|
|
231
|
+
align-content: center;
|
|
232
|
+
background:
|
|
233
|
+
linear-gradient(90deg, rgba(0, 191, 216, 0.14) 0 32%, transparent 32% 100%),
|
|
234
|
+
repeating-linear-gradient(0deg, transparent 0 23px, rgba(17, 17, 17, 0.06) 23px 24px),
|
|
235
|
+
var(--paper);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
.hero-inner,
|
|
239
|
+
.section-inner {
|
|
240
|
+
max-width: 1180px;
|
|
241
|
+
margin: 0 auto;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
.eyebrow {
|
|
245
|
+
margin: 0 0 14px;
|
|
246
|
+
font-family: var(--mono);
|
|
247
|
+
font-size: 0.8rem;
|
|
248
|
+
font-weight: 800;
|
|
249
|
+
text-transform: uppercase;
|
|
250
|
+
letter-spacing: 0.08em;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
.hero h2 {
|
|
254
|
+
max-width: 980px;
|
|
255
|
+
margin: 0;
|
|
256
|
+
font-family: var(--mono);
|
|
257
|
+
font-size: clamp(2.3rem, 6vw, 5.2rem);
|
|
258
|
+
line-height: 1.02;
|
|
259
|
+
letter-spacing: 0;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
.hero-summary {
|
|
263
|
+
max-width: 860px;
|
|
264
|
+
margin: 28px 0 0;
|
|
265
|
+
font-size: 1.24rem;
|
|
266
|
+
line-height: 1.55;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
.hero-meta {
|
|
270
|
+
display: grid;
|
|
271
|
+
grid-template-columns: repeat(4, minmax(0, 1fr));
|
|
272
|
+
gap: 14px;
|
|
273
|
+
margin-top: 44px;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
.meta-box,
|
|
277
|
+
.concept,
|
|
278
|
+
.callout,
|
|
279
|
+
.source-box,
|
|
280
|
+
.step,
|
|
281
|
+
.principle,
|
|
282
|
+
.surface,
|
|
283
|
+
.adapter-rule {
|
|
284
|
+
background: var(--white);
|
|
285
|
+
border: 3px solid var(--line);
|
|
286
|
+
box-shadow: var(--shadow);
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
.meta-box {
|
|
290
|
+
padding: 16px;
|
|
291
|
+
min-height: 104px;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
.meta-box strong {
|
|
295
|
+
display: block;
|
|
296
|
+
margin-bottom: 10px;
|
|
297
|
+
font-family: var(--mono);
|
|
298
|
+
font-size: 0.78rem;
|
|
299
|
+
text-transform: uppercase;
|
|
300
|
+
letter-spacing: 0.07em;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
.meta-box span {
|
|
304
|
+
display: block;
|
|
305
|
+
color: var(--muted);
|
|
306
|
+
font-size: 0.95rem;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
.section:nth-child(even) {
|
|
310
|
+
background: var(--white);
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
.section-number {
|
|
314
|
+
margin: 0 0 8px;
|
|
315
|
+
font-family: var(--mono);
|
|
316
|
+
font-weight: 800;
|
|
317
|
+
color: var(--muted);
|
|
318
|
+
text-transform: uppercase;
|
|
319
|
+
letter-spacing: 0.08em;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
.section h2 {
|
|
323
|
+
margin: 0 0 28px;
|
|
324
|
+
padding-bottom: 14px;
|
|
325
|
+
border-bottom: 4px solid var(--line);
|
|
326
|
+
font-family: var(--mono);
|
|
327
|
+
font-size: clamp(1.9rem, 4vw, 3.25rem);
|
|
328
|
+
line-height: 1.1;
|
|
329
|
+
letter-spacing: 0;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
.section h3 {
|
|
333
|
+
margin: 36px 0 12px;
|
|
334
|
+
font-family: var(--mono);
|
|
335
|
+
font-size: 1.28rem;
|
|
336
|
+
line-height: 1.25;
|
|
337
|
+
letter-spacing: 0;
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
.lead {
|
|
341
|
+
max-width: 920px;
|
|
342
|
+
margin: 0 0 28px;
|
|
343
|
+
font-size: 1.12rem;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
.grid-2,
|
|
347
|
+
.grid-3,
|
|
348
|
+
.grid-4 {
|
|
349
|
+
display: grid;
|
|
350
|
+
gap: 18px;
|
|
351
|
+
margin: 24px 0;
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
.grid-2 {
|
|
355
|
+
grid-template-columns: repeat(2, minmax(0, 1fr));
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
.grid-3 {
|
|
359
|
+
grid-template-columns: repeat(3, minmax(0, 1fr));
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
.grid-4 {
|
|
363
|
+
grid-template-columns: repeat(4, minmax(0, 1fr));
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
.concept,
|
|
367
|
+
.source-box,
|
|
368
|
+
.principle,
|
|
369
|
+
.surface,
|
|
370
|
+
.adapter-rule {
|
|
371
|
+
padding: 20px;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
.concept h3,
|
|
375
|
+
.source-box h3,
|
|
376
|
+
.principle h3,
|
|
377
|
+
.surface h3,
|
|
378
|
+
.adapter-rule h3 {
|
|
379
|
+
margin-top: 0;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
.concept p,
|
|
383
|
+
.source-box p,
|
|
384
|
+
.principle p,
|
|
385
|
+
.surface p,
|
|
386
|
+
.adapter-rule p {
|
|
387
|
+
margin-bottom: 0;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
.callout {
|
|
391
|
+
padding: 22px;
|
|
392
|
+
margin: 28px 0;
|
|
393
|
+
background: var(--cyan);
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
.callout h3 {
|
|
397
|
+
margin-top: 0;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
.callout p:last-child {
|
|
401
|
+
margin-bottom: 0;
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
.diagram-frame {
|
|
405
|
+
margin: 28px 0;
|
|
406
|
+
padding: 18px;
|
|
407
|
+
overflow-x: auto;
|
|
408
|
+
background: var(--white);
|
|
409
|
+
border: 3px solid var(--line);
|
|
410
|
+
box-shadow: var(--shadow);
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
.diagram {
|
|
414
|
+
width: 100%;
|
|
415
|
+
min-width: 920px;
|
|
416
|
+
height: auto;
|
|
417
|
+
display: block;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
.box {
|
|
421
|
+
fill: #ffffff;
|
|
422
|
+
stroke: #111111;
|
|
423
|
+
stroke-width: 3;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
.box-cyan {
|
|
427
|
+
fill: #b9f5ff;
|
|
428
|
+
stroke: #111111;
|
|
429
|
+
stroke-width: 3;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
.box-soft {
|
|
433
|
+
fill: #f0f0e8;
|
|
434
|
+
stroke: #111111;
|
|
435
|
+
stroke-width: 3;
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
.box-green {
|
|
439
|
+
fill: #d7f4df;
|
|
440
|
+
stroke: #111111;
|
|
441
|
+
stroke-width: 3;
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
.box-yellow {
|
|
445
|
+
fill: #fff1b8;
|
|
446
|
+
stroke: #111111;
|
|
447
|
+
stroke-width: 3;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
.diagram text {
|
|
451
|
+
font-family: var(--mono);
|
|
452
|
+
font-size: 13px;
|
|
453
|
+
fill: #111111;
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
.diagram .small {
|
|
457
|
+
font-family: var(--sans);
|
|
458
|
+
font-size: 11px;
|
|
459
|
+
fill: #333333;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
.diagram .label {
|
|
463
|
+
font-size: 12px;
|
|
464
|
+
font-weight: 800;
|
|
465
|
+
letter-spacing: 0.05em;
|
|
466
|
+
text-transform: uppercase;
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
.arrow {
|
|
470
|
+
stroke: #111111;
|
|
471
|
+
stroke-width: 3;
|
|
472
|
+
fill: none;
|
|
473
|
+
marker-end: url(#arrow);
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
.step-list {
|
|
477
|
+
display: grid;
|
|
478
|
+
gap: 16px;
|
|
479
|
+
margin: 24px 0;
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
.step {
|
|
483
|
+
display: grid;
|
|
484
|
+
grid-template-columns: 78px minmax(0, 1fr);
|
|
485
|
+
gap: 18px;
|
|
486
|
+
padding: 18px;
|
|
487
|
+
box-shadow: none;
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
.step-num {
|
|
491
|
+
display: grid;
|
|
492
|
+
place-items: center;
|
|
493
|
+
width: 58px;
|
|
494
|
+
height: 58px;
|
|
495
|
+
background: var(--ink);
|
|
496
|
+
color: var(--white);
|
|
497
|
+
border: 3px solid var(--line);
|
|
498
|
+
font-family: var(--mono);
|
|
499
|
+
font-size: 1.2rem;
|
|
500
|
+
font-weight: 800;
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
.step h3 {
|
|
504
|
+
margin-top: 0;
|
|
505
|
+
margin-bottom: 8px;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
.step p {
|
|
509
|
+
margin-top: 0;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
.tag-row {
|
|
513
|
+
display: flex;
|
|
514
|
+
flex-wrap: wrap;
|
|
515
|
+
gap: 8px;
|
|
516
|
+
margin: 14px 0 0;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
.tag {
|
|
520
|
+
display: inline-flex;
|
|
521
|
+
align-items: center;
|
|
522
|
+
min-height: 30px;
|
|
523
|
+
padding: 4px 8px;
|
|
524
|
+
border: 2px solid var(--line);
|
|
525
|
+
background: var(--soft);
|
|
526
|
+
font-family: var(--mono);
|
|
527
|
+
font-size: 0.76rem;
|
|
528
|
+
font-weight: 700;
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
.tag.cyan {
|
|
532
|
+
background: var(--cyan);
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
.tag.green {
|
|
536
|
+
background: #d7f4df;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
.tag.yellow {
|
|
540
|
+
background: #fff1b8;
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
.tag.red {
|
|
544
|
+
background: #ffd9d6;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
.timeline {
|
|
548
|
+
position: relative;
|
|
549
|
+
display: grid;
|
|
550
|
+
gap: 14px;
|
|
551
|
+
margin: 24px 0;
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
.timeline-item {
|
|
555
|
+
display: grid;
|
|
556
|
+
grid-template-columns: 190px minmax(0, 1fr);
|
|
557
|
+
gap: 18px;
|
|
558
|
+
padding: 16px;
|
|
559
|
+
background: var(--white);
|
|
560
|
+
border: 3px solid var(--line);
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
.timeline-time {
|
|
564
|
+
font-family: var(--mono);
|
|
565
|
+
font-weight: 800;
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
.timeline-body h3 {
|
|
569
|
+
margin: 0 0 6px;
|
|
570
|
+
font-size: 1rem;
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
.timeline-body p {
|
|
574
|
+
margin: 0;
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
.pill {
|
|
578
|
+
display: inline-block;
|
|
579
|
+
padding: 2px 7px;
|
|
580
|
+
margin-right: 4px;
|
|
581
|
+
border: 2px solid var(--line);
|
|
582
|
+
background: var(--soft);
|
|
583
|
+
font-family: var(--mono);
|
|
584
|
+
font-size: 0.75rem;
|
|
585
|
+
font-weight: 800;
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
.source-list {
|
|
589
|
+
display: grid;
|
|
590
|
+
gap: 14px;
|
|
591
|
+
margin: 24px 0;
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
.source-box {
|
|
595
|
+
box-shadow: none;
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
.source-box h3 {
|
|
599
|
+
font-size: 1rem;
|
|
600
|
+
}
|
|
601
|
+
|
|
602
|
+
.source-box ul {
|
|
603
|
+
margin-bottom: 0;
|
|
604
|
+
}
|
|
605
|
+
|
|
606
|
+
.footer-note {
|
|
607
|
+
padding: 28px clamp(28px, 6vw, 88px);
|
|
608
|
+
background: var(--ink);
|
|
609
|
+
color: var(--white);
|
|
610
|
+
font-family: var(--mono);
|
|
611
|
+
font-size: 0.9rem;
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
.footer-note a {
|
|
615
|
+
color: var(--cyan);
|
|
616
|
+
}
|
|
617
|
+
|
|
618
|
+
.kbd-row {
|
|
619
|
+
display: flex;
|
|
620
|
+
flex-wrap: wrap;
|
|
621
|
+
gap: 8px;
|
|
622
|
+
margin: 12px 0;
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
kbd {
|
|
626
|
+
display: inline-flex;
|
|
627
|
+
align-items: center;
|
|
628
|
+
min-height: 32px;
|
|
629
|
+
padding: 3px 8px;
|
|
630
|
+
background: var(--white);
|
|
631
|
+
border: 2px solid var(--line);
|
|
632
|
+
box-shadow: 3px 3px 0 var(--line);
|
|
633
|
+
font-size: 0.82rem;
|
|
634
|
+
font-weight: 700;
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
@media (max-width: 980px) {
|
|
638
|
+
.layout {
|
|
639
|
+
display: block;
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
.sidebar {
|
|
643
|
+
position: relative;
|
|
644
|
+
height: auto;
|
|
645
|
+
border-right: 0;
|
|
646
|
+
border-bottom: 4px solid var(--line);
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
.hero,
|
|
650
|
+
.section {
|
|
651
|
+
min-height: auto;
|
|
652
|
+
padding: 44px 22px;
|
|
653
|
+
}
|
|
654
|
+
|
|
655
|
+
.hero-meta,
|
|
656
|
+
.grid-2,
|
|
657
|
+
.grid-3,
|
|
658
|
+
.grid-4,
|
|
659
|
+
.timeline-item {
|
|
660
|
+
grid-template-columns: 1fr;
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
.step {
|
|
664
|
+
grid-template-columns: 1fr;
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
.diagram {
|
|
668
|
+
min-width: 760px;
|
|
669
|
+
}
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
@media (prefers-reduced-motion: reduce) {
|
|
673
|
+
html {
|
|
674
|
+
scroll-behavior: auto;
|
|
675
|
+
}
|
|
676
|
+
}
|
|
677
|
+
</style>
|
|
678
|
+
</head>
|
|
679
|
+
<body>
|
|
680
|
+
<a class="skip-link" href="#main">Skip to architecture tutorial</a>
|
|
681
|
+
<div class="layout">
|
|
682
|
+
<aside class="sidebar" aria-label="Architecture navigation">
|
|
683
|
+
<div class="brand">
|
|
684
|
+
<span class="brand-label">Eagle Mem</span>
|
|
685
|
+
<h1>Agent Architecture Tutorial</h1>
|
|
686
|
+
<p>Technical architecture plus UX architecture for Claude Code, Codex, and future coding agents.</p>
|
|
687
|
+
</div>
|
|
688
|
+
|
|
689
|
+
<p class="nav-title">Start Here</p>
|
|
690
|
+
<nav>
|
|
691
|
+
<ul class="nav-list">
|
|
692
|
+
<li><a href="#purpose">01. Purpose</a></li>
|
|
693
|
+
<li><a href="#basics">02. Basics</a></li>
|
|
694
|
+
<li><a href="#system-map">03. System Map</a></li>
|
|
695
|
+
<li><a href="#install">04. Install Runtime</a></li>
|
|
696
|
+
<li><a href="#lifecycle">05. Hook Lifecycle</a></li>
|
|
697
|
+
</ul>
|
|
698
|
+
|
|
699
|
+
<p class="nav-title">Technical</p>
|
|
700
|
+
<ul class="nav-list">
|
|
701
|
+
<li><a href="#agent-adapter">06. Agent Adapter</a></li>
|
|
702
|
+
<li><a href="#database">07. Database Layer</a></li>
|
|
703
|
+
<li><a href="#recall">08. Recall Flow</a></li>
|
|
704
|
+
<li><a href="#guardrails">09. Guardrail Flow</a></li>
|
|
705
|
+
<li><a href="#lanes">10. Worker Lanes</a></li>
|
|
706
|
+
</ul>
|
|
707
|
+
|
|
708
|
+
<p class="nav-title">UX</p>
|
|
709
|
+
<ul class="nav-list">
|
|
710
|
+
<li><a href="#ux-principles">11. UX Principles</a></li>
|
|
711
|
+
<li><a href="#ux-surfaces">12. UX Surfaces</a></li>
|
|
712
|
+
<li><a href="#tutorial">13. Beginner Tutorial</a></li>
|
|
713
|
+
<li><a href="#future-agents">14. Future Agents</a></li>
|
|
714
|
+
<li><a href="#source-map">15. Source Map</a></li>
|
|
715
|
+
</ul>
|
|
716
|
+
</nav>
|
|
717
|
+
</aside>
|
|
718
|
+
|
|
719
|
+
<main id="main">
|
|
720
|
+
<section class="hero" id="purpose">
|
|
721
|
+
<div class="hero-inner">
|
|
722
|
+
<p class="eyebrow">Architecture guide - technical + UX - updated 2026-05-05</p>
|
|
723
|
+
<h2>Eagle Mem is a local memory and safety layer that makes AI coding agents start warmer, ship safer, and coordinate better.</h2>
|
|
724
|
+
<p class="hero-summary">
|
|
725
|
+
This tutorial explains the project from first principles. You do not need to know the codebase first. Read it like a guided tour: what problem Eagle Mem solves, how hooks move data through the system, how SQLite stores shared memory, and why the user experience is intentionally quiet until the agent needs help.
|
|
726
|
+
</p>
|
|
727
|
+
|
|
728
|
+
<div class="hero-meta">
|
|
729
|
+
<div class="meta-box">
|
|
730
|
+
<strong>Runtime</strong>
|
|
731
|
+
<span>Bash hooks, CLI scripts, SQLite/FTS5, jq, optional RTK.</span>
|
|
732
|
+
</div>
|
|
733
|
+
<div class="meta-box">
|
|
734
|
+
<strong>Agents</strong>
|
|
735
|
+
<span>Claude Code and Codex today; adapter contract for more agents later.</span>
|
|
736
|
+
</div>
|
|
737
|
+
<div class="meta-box">
|
|
738
|
+
<strong>Core Promise</strong>
|
|
739
|
+
<span>Recall, guardrails, token savings, worker lanes.</span>
|
|
740
|
+
</div>
|
|
741
|
+
<div class="meta-box">
|
|
742
|
+
<strong>UX Shape</strong>
|
|
743
|
+
<span>Small contextual messages inside the agent flow, not a separate app.</span>
|
|
744
|
+
</div>
|
|
745
|
+
</div>
|
|
746
|
+
</div>
|
|
747
|
+
</section>
|
|
748
|
+
|
|
749
|
+
<section class="section" id="basics">
|
|
750
|
+
<div class="section-inner">
|
|
751
|
+
<p class="section-number">02 / Basics</p>
|
|
752
|
+
<h2>The Mental Model</h2>
|
|
753
|
+
<p class="lead">
|
|
754
|
+
Eagle Mem exists because coding agents are powerful but forgetful. A normal agent session has short-lived context. Eagle Mem adds a local layer around that session so important history, decisions, tasks, and feature risks survive between turns, compactions, and even different agents.
|
|
755
|
+
</p>
|
|
756
|
+
|
|
757
|
+
<div class="grid-3">
|
|
758
|
+
<article class="concept">
|
|
759
|
+
<h3>1. Recall</h3>
|
|
760
|
+
<p>Recall means the next agent can see useful project history without rereading everything. Eagle Mem stores session summaries, project overviews, agent memories, task state, and indexed source chunks in one local SQLite database.</p>
|
|
761
|
+
<div class="tag-row">
|
|
762
|
+
<span class="tag cyan">SessionStart</span>
|
|
763
|
+
<span class="tag cyan">UserPromptSubmit</span>
|
|
764
|
+
<span class="tag">FTS5</span>
|
|
765
|
+
</div>
|
|
766
|
+
</article>
|
|
767
|
+
|
|
768
|
+
<article class="concept">
|
|
769
|
+
<h3>2. Guardrails</h3>
|
|
770
|
+
<p>Guardrails mean the agent gets warned before it repeats known mistakes, reverts decisions, edits sensitive files, or tries to release code before impacted features have been verified.</p>
|
|
771
|
+
<div class="tag-row">
|
|
772
|
+
<span class="tag yellow">PreToolUse</span>
|
|
773
|
+
<span class="tag yellow">PostToolUse</span>
|
|
774
|
+
<span class="tag">Feature verification</span>
|
|
775
|
+
</div>
|
|
776
|
+
</article>
|
|
777
|
+
|
|
778
|
+
<article class="concept">
|
|
779
|
+
<h3>3. Lanes</h3>
|
|
780
|
+
<p>Lanes let broad work split across agents. A coordinator can create durable worker lanes with owners, worktrees, validation commands, status notes, and handoffs that survive compaction.</p>
|
|
781
|
+
<div class="tag-row">
|
|
782
|
+
<span class="tag green">orchestrate</span>
|
|
783
|
+
<span class="tag green">agent_tasks</span>
|
|
784
|
+
<span class="tag">Worktrees</span>
|
|
785
|
+
</div>
|
|
786
|
+
</article>
|
|
787
|
+
</div>
|
|
788
|
+
|
|
789
|
+
<div class="callout">
|
|
790
|
+
<h3>The simplest explanation</h3>
|
|
791
|
+
<p>Eagle Mem is not a hosted memory service. It is not a vector database. It is a local runtime made of hook scripts, CLI commands, and a SQLite database. Agents keep working in their normal terminal UI, while Eagle Mem quietly injects context, records what happened, and blocks risky release boundaries when verification is still pending.</p>
|
|
792
|
+
</div>
|
|
793
|
+
|
|
794
|
+
<h3>Vocabulary</h3>
|
|
795
|
+
<table>
|
|
796
|
+
<thead>
|
|
797
|
+
<tr>
|
|
798
|
+
<th>Term</th>
|
|
799
|
+
<th>Plain-English Meaning</th>
|
|
800
|
+
<th>Where It Lives</th>
|
|
801
|
+
</tr>
|
|
802
|
+
</thead>
|
|
803
|
+
<tbody>
|
|
804
|
+
<tr>
|
|
805
|
+
<td><code>Session</code></td>
|
|
806
|
+
<td>One agent conversation or run in a project.</td>
|
|
807
|
+
<td><code>sessions</code> table</td>
|
|
808
|
+
</tr>
|
|
809
|
+
<tr>
|
|
810
|
+
<td><code>Hook</code></td>
|
|
811
|
+
<td>A script the agent calls at a specific lifecycle moment, such as startup or before a tool call.</td>
|
|
812
|
+
<td><code>hooks/*.sh</code></td>
|
|
813
|
+
</tr>
|
|
814
|
+
<tr>
|
|
815
|
+
<td><code>Observation</code></td>
|
|
816
|
+
<td>A lightweight record of one tool action: read, edit, shell command, output size, and touched files.</td>
|
|
817
|
+
<td><code>observations</code> table</td>
|
|
818
|
+
</tr>
|
|
819
|
+
<tr>
|
|
820
|
+
<td><code>Summary</code></td>
|
|
821
|
+
<td>The durable lesson from a session: request, completed work, learned context, decisions, gotchas, and files.</td>
|
|
822
|
+
<td><code>summaries</code> and <code>summaries_fts</code></td>
|
|
823
|
+
</tr>
|
|
824
|
+
<tr>
|
|
825
|
+
<td><code>Feature</code></td>
|
|
826
|
+
<td>A user-facing or system behavior mapped to files, dependencies, and smoke tests.</td>
|
|
827
|
+
<td><code>features</code>, <code>feature_files</code>, <code>feature_smoke_tests</code></td>
|
|
828
|
+
</tr>
|
|
829
|
+
<tr>
|
|
830
|
+
<td><code>Lane</code></td>
|
|
831
|
+
<td>An isolated workstream assigned to an agent, usually in a git worktree.</td>
|
|
832
|
+
<td><code>orchestrations</code>, <code>orchestration_lanes</code></td>
|
|
833
|
+
</tr>
|
|
834
|
+
</tbody>
|
|
835
|
+
</table>
|
|
836
|
+
</div>
|
|
837
|
+
</section>
|
|
838
|
+
|
|
839
|
+
<section class="section" id="system-map">
|
|
840
|
+
<div class="section-inner">
|
|
841
|
+
<p class="section-number">03 / System Map</p>
|
|
842
|
+
<h2>The Whole System At Once</h2>
|
|
843
|
+
<p class="lead">
|
|
844
|
+
Think of Eagle Mem as five layers. The user interacts with an agent. The agent fires hooks. The hooks call shared library functions. The library reads and writes SQLite. CLI commands and skills expose the same state to humans and agents.
|
|
845
|
+
</p>
|
|
846
|
+
|
|
847
|
+
<div class="diagram-frame" role="img" aria-labelledby="system-map-title system-map-desc">
|
|
848
|
+
<svg class="diagram" viewBox="0 0 1100 620" xmlns="http://www.w3.org/2000/svg">
|
|
849
|
+
<title id="system-map-title">Eagle Mem technical system map</title>
|
|
850
|
+
<desc id="system-map-desc">A layered architecture showing user, agents, hooks, shared libraries, SQLite, CLI commands, and skills.</desc>
|
|
851
|
+
<defs>
|
|
852
|
+
<marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
|
|
853
|
+
<path d="M0,0 L0,6 L9,3 z" fill="#111111"></path>
|
|
854
|
+
</marker>
|
|
855
|
+
</defs>
|
|
856
|
+
|
|
857
|
+
<text x="40" y="42" class="label">User Layer</text>
|
|
858
|
+
<rect x="40" y="58" width="220" height="72" class="box-cyan"></rect>
|
|
859
|
+
<text x="62" y="90">Developer</text>
|
|
860
|
+
<text x="62" y="112" class="small">Works in Claude Code or Codex</text>
|
|
861
|
+
|
|
862
|
+
<text x="40" y="178" class="label">Agent Layer</text>
|
|
863
|
+
<rect x="40" y="194" width="220" height="78" class="box"></rect>
|
|
864
|
+
<text x="62" y="225">Claude Code</text>
|
|
865
|
+
<text x="62" y="247" class="small">settings.json, CLAUDE.md, skills</text>
|
|
866
|
+
<rect x="300" y="194" width="220" height="78" class="box"></rect>
|
|
867
|
+
<text x="322" y="225">Codex</text>
|
|
868
|
+
<text x="322" y="247" class="small">config.toml, hooks.json, AGENTS.md</text>
|
|
869
|
+
|
|
870
|
+
<text x="40" y="320" class="label">Hook Runtime</text>
|
|
871
|
+
<rect x="40" y="336" width="160" height="68" class="box-soft"></rect>
|
|
872
|
+
<text x="58" y="365">SessionStart</text>
|
|
873
|
+
<text x="58" y="386" class="small">inject recall</text>
|
|
874
|
+
<rect x="220" y="336" width="160" height="68" class="box-soft"></rect>
|
|
875
|
+
<text x="238" y="365">Prompt</text>
|
|
876
|
+
<text x="238" y="386" class="small">search memory</text>
|
|
877
|
+
<rect x="400" y="336" width="160" height="68" class="box-soft"></rect>
|
|
878
|
+
<text x="418" y="365">PreToolUse</text>
|
|
879
|
+
<text x="418" y="386" class="small">guard, block, rewrite</text>
|
|
880
|
+
<rect x="580" y="336" width="160" height="68" class="box-soft"></rect>
|
|
881
|
+
<text x="598" y="365">PostToolUse</text>
|
|
882
|
+
<text x="598" y="386" class="small">record observations</text>
|
|
883
|
+
<rect x="760" y="336" width="160" height="68" class="box-soft"></rect>
|
|
884
|
+
<text x="778" y="365">Stop/End</text>
|
|
885
|
+
<text x="778" y="386" class="small">save summary</text>
|
|
886
|
+
|
|
887
|
+
<text x="40" y="452" class="label">Shared Runtime + Data</text>
|
|
888
|
+
<rect x="40" y="468" width="245" height="80" class="box-yellow"></rect>
|
|
889
|
+
<text x="62" y="498">lib/*.sh</text>
|
|
890
|
+
<text x="62" y="520" class="small">agent detection, project keys, DB helpers</text>
|
|
891
|
+
<rect x="325" y="468" width="245" height="80" class="box-green"></rect>
|
|
892
|
+
<text x="347" y="498">~/.eagle-mem/memory.db</text>
|
|
893
|
+
<text x="347" y="520" class="small">SQLite WAL + FTS5 tables</text>
|
|
894
|
+
<rect x="610" y="468" width="245" height="80" class="box-cyan"></rect>
|
|
895
|
+
<text x="632" y="498">CLI + Skills</text>
|
|
896
|
+
<text x="632" y="520" class="small">search, feature, guard, orchestrate</text>
|
|
897
|
+
|
|
898
|
+
<path d="M150,130 L150,190" class="arrow"></path>
|
|
899
|
+
<path d="M260,232 L300,232" class="arrow"></path>
|
|
900
|
+
<path d="M150,272 L150,330" class="arrow"></path>
|
|
901
|
+
<path d="M410,272 L410,330" class="arrow"></path>
|
|
902
|
+
<path d="M840,404 L735,462" class="arrow"></path>
|
|
903
|
+
<path d="M660,404 L452,462" class="arrow"></path>
|
|
904
|
+
<path d="M300,404 L182,462" class="arrow"></path>
|
|
905
|
+
<path d="M285,508 L320,508" class="arrow"></path>
|
|
906
|
+
<path d="M570,508 L605,508" class="arrow"></path>
|
|
907
|
+
</svg>
|
|
908
|
+
</div>
|
|
909
|
+
|
|
910
|
+
<h3>Key architectural decision</h3>
|
|
911
|
+
<p>
|
|
912
|
+
Eagle Mem does not make every agent learn a new API. Instead, each agent gets a thin adapter that registers its native hook format and points those hooks at the same installed scripts under <code>~/.eagle-mem</code>. Once a hook script starts, it normalizes the agent source and uses the same library and database functions as every other agent.
|
|
913
|
+
</p>
|
|
914
|
+
</div>
|
|
915
|
+
</section>
|
|
916
|
+
|
|
917
|
+
<section class="section" id="install">
|
|
918
|
+
<div class="section-inner">
|
|
919
|
+
<p class="section-number">04 / Install Runtime</p>
|
|
920
|
+
<h2>What Happens During Install</h2>
|
|
921
|
+
<p class="lead">
|
|
922
|
+
Installation converts the source package into a local runtime. The source repo stays the product code. The installed runtime under <code>~/.eagle-mem</code> is what the agents actually execute from hooks.
|
|
923
|
+
</p>
|
|
924
|
+
|
|
925
|
+
<div class="step-list">
|
|
926
|
+
<article class="step">
|
|
927
|
+
<div class="step-num">1</div>
|
|
928
|
+
<div>
|
|
929
|
+
<h3>User installs the CLI</h3>
|
|
930
|
+
<p>The user runs <code>npm install -g eagle-mem</code>, then <code>eagle-mem install</code>. The bin entry dispatches to scripts such as <code>install.sh</code>, <code>search.sh</code>, <code>feature.sh</code>, and <code>orchestrate.sh</code>.</p>
|
|
931
|
+
</div>
|
|
932
|
+
</article>
|
|
933
|
+
|
|
934
|
+
<article class="step">
|
|
935
|
+
<div class="step-num">2</div>
|
|
936
|
+
<div>
|
|
937
|
+
<h3>Prerequisites are checked</h3>
|
|
938
|
+
<p>The installer checks for an FTS5-capable <code>sqlite3</code>, <code>jq</code>, optional <code>rtk</code>, and at least one supported agent installation. FTS5 matters because summaries, code chunks, and mirrored artifacts are searched with SQLite full-text search.</p>
|
|
939
|
+
</div>
|
|
940
|
+
</article>
|
|
941
|
+
|
|
942
|
+
<article class="step">
|
|
943
|
+
<div class="step-num">3</div>
|
|
944
|
+
<div>
|
|
945
|
+
<h3>Runtime files are copied</h3>
|
|
946
|
+
<p>The hook scripts, shared libraries, migrations, and CLI support scripts are copied into <code>~/.eagle-mem</code>. This makes the runtime independent of the current checkout location.</p>
|
|
947
|
+
</div>
|
|
948
|
+
</article>
|
|
949
|
+
|
|
950
|
+
<article class="step">
|
|
951
|
+
<div class="step-num">4</div>
|
|
952
|
+
<div>
|
|
953
|
+
<h3>Database migrations run</h3>
|
|
954
|
+
<p><code>db/migrate.sh</code> creates or updates <code>~/.eagle-mem/memory.db</code>. Runtime connections enable WAL mode, foreign keys, and a busy timeout so hook writes can coexist during active agent sessions.</p>
|
|
955
|
+
</div>
|
|
956
|
+
</article>
|
|
957
|
+
|
|
958
|
+
<article class="step">
|
|
959
|
+
<div class="step-num">5</div>
|
|
960
|
+
<div>
|
|
961
|
+
<h3>Agent hooks are registered</h3>
|
|
962
|
+
<p>Claude Code hooks are patched into <code>~/.claude/settings.json</code>. Codex hooks are registered in <code>~/.codex/hooks.json</code>, and <code>codex_hooks = true</code> is enabled in <code>~/.codex/config.toml</code>.</p>
|
|
963
|
+
</div>
|
|
964
|
+
</article>
|
|
965
|
+
|
|
966
|
+
<article class="step">
|
|
967
|
+
<div class="step-num">6</div>
|
|
968
|
+
<div>
|
|
969
|
+
<h3>Skills and instructions are linked</h3>
|
|
970
|
+
<p>Eagle Mem skills are symlinked into each agent's skill directory. Claude receives <code>CLAUDE.md</code> summary instructions. Codex receives <code>AGENTS.md</code> clean-output memory instructions.</p>
|
|
971
|
+
</div>
|
|
972
|
+
</article>
|
|
973
|
+
</div>
|
|
974
|
+
|
|
975
|
+
<h3>Install topology</h3>
|
|
976
|
+
<table>
|
|
977
|
+
<thead>
|
|
978
|
+
<tr>
|
|
979
|
+
<th>Path</th>
|
|
980
|
+
<th>Role</th>
|
|
981
|
+
<th>Why It Exists</th>
|
|
982
|
+
</tr>
|
|
983
|
+
</thead>
|
|
984
|
+
<tbody>
|
|
985
|
+
<tr>
|
|
986
|
+
<td><code>bin/eagle-mem</code></td>
|
|
987
|
+
<td>Command dispatcher</td>
|
|
988
|
+
<td>Maps CLI subcommands to scripts under <code>scripts/</code>.</td>
|
|
989
|
+
</tr>
|
|
990
|
+
<tr>
|
|
991
|
+
<td><code>~/.eagle-mem/hooks/</code></td>
|
|
992
|
+
<td>Installed hook entrypoints</td>
|
|
993
|
+
<td>Stable scripts that agent configs can call.</td>
|
|
994
|
+
</tr>
|
|
995
|
+
<tr>
|
|
996
|
+
<td><code>~/.eagle-mem/lib/</code></td>
|
|
997
|
+
<td>Shared runtime functions</td>
|
|
998
|
+
<td>Keeps project detection, agent detection, database access, guardrails, and redaction in one place.</td>
|
|
999
|
+
</tr>
|
|
1000
|
+
<tr>
|
|
1001
|
+
<td><code>~/.eagle-mem/db/</code></td>
|
|
1002
|
+
<td>Migrations and schema</td>
|
|
1003
|
+
<td>Creates the local SQLite/FTS5 database.</td>
|
|
1004
|
+
</tr>
|
|
1005
|
+
<tr>
|
|
1006
|
+
<td><code>~/.eagle-mem/scripts/</code></td>
|
|
1007
|
+
<td>CLI command implementations</td>
|
|
1008
|
+
<td>Lets users and agents search, verify, curate, orchestrate, and inspect status.</td>
|
|
1009
|
+
</tr>
|
|
1010
|
+
<tr>
|
|
1011
|
+
<td><code>~/.eagle-mem/memory.db</code></td>
|
|
1012
|
+
<td>Single source of local memory</td>
|
|
1013
|
+
<td>Stores shared state across Claude Code, Codex, compactions, and sessions.</td>
|
|
1014
|
+
</tr>
|
|
1015
|
+
</tbody>
|
|
1016
|
+
</table>
|
|
1017
|
+
</div>
|
|
1018
|
+
</section>
|
|
1019
|
+
|
|
1020
|
+
<section class="section" id="lifecycle">
|
|
1021
|
+
<div class="section-inner">
|
|
1022
|
+
<p class="section-number">05 / Hook Lifecycle</p>
|
|
1023
|
+
<h2>The Runtime Flow From Start To Stop</h2>
|
|
1024
|
+
<p class="lead">
|
|
1025
|
+
The hook lifecycle is the heart of Eagle Mem. The agent does not need to remember to run anything. It naturally starts, receives user prompts, uses tools, and ends turns. Eagle Mem attaches useful behavior to those moments.
|
|
1026
|
+
</p>
|
|
1027
|
+
|
|
1028
|
+
<div class="timeline">
|
|
1029
|
+
<div class="timeline-item">
|
|
1030
|
+
<div class="timeline-time">SessionStart</div>
|
|
1031
|
+
<div class="timeline-body">
|
|
1032
|
+
<h3>Start warm</h3>
|
|
1033
|
+
<p>Upserts the session, auto-provisions scan/index/prune/curate jobs, checks updates, and injects a compact banner, overview, recent recall, stored memories, tasks, and code hints.</p>
|
|
1034
|
+
</div>
|
|
1035
|
+
</div>
|
|
1036
|
+
<div class="timeline-item">
|
|
1037
|
+
<div class="timeline-time">UserPromptSubmit</div>
|
|
1038
|
+
<div class="timeline-body">
|
|
1039
|
+
<h3>Search only when the prompt is meaningful</h3>
|
|
1040
|
+
<p>Tracks turn count for context pressure, searches summaries and indexed code through FTS5, and injects relevant recall. Broad-work prompts can also trigger the orchestration protocol reminder.</p>
|
|
1041
|
+
</div>
|
|
1042
|
+
</div>
|
|
1043
|
+
<div class="timeline-item">
|
|
1044
|
+
<div class="timeline-time">PreToolUse</div>
|
|
1045
|
+
<div class="timeline-body">
|
|
1046
|
+
<h3>Warn before action</h3>
|
|
1047
|
+
<p>Runs before shell commands and mutations. It can block release-boundary commands with pending feature verification, rewrite raw shell output through RTK, and surface guardrails before edits.</p>
|
|
1048
|
+
</div>
|
|
1049
|
+
</div>
|
|
1050
|
+
<div class="timeline-item">
|
|
1051
|
+
<div class="timeline-time">PostToolUse</div>
|
|
1052
|
+
<div class="timeline-body">
|
|
1053
|
+
<h3>Record what happened</h3>
|
|
1054
|
+
<p>Stores observations, mirrors agent memories/plans/tasks, records pending feature verification after edits, surfaces stale-memory warnings, and reminds the agent about file-specific decisions or feature dependencies.</p>
|
|
1055
|
+
</div>
|
|
1056
|
+
</div>
|
|
1057
|
+
<div class="timeline-item">
|
|
1058
|
+
<div class="timeline-time">Stop</div>
|
|
1059
|
+
<div class="timeline-body">
|
|
1060
|
+
<h3>Save the lesson</h3>
|
|
1061
|
+
<p>Runs at turn end. It reconciles current diffs into pending feature verification, extracts explicit summary fields when available, falls back to heuristic summaries, and queues LLM enrichment in the background.</p>
|
|
1062
|
+
</div>
|
|
1063
|
+
</div>
|
|
1064
|
+
<div class="timeline-item">
|
|
1065
|
+
<div class="timeline-time">SessionEnd</div>
|
|
1066
|
+
<div class="timeline-body">
|
|
1067
|
+
<h3>Close the loop</h3>
|
|
1068
|
+
<p>Re-syncs task files, marks the session completed, and prunes older observations for the project.</p>
|
|
1069
|
+
</div>
|
|
1070
|
+
</div>
|
|
1071
|
+
</div>
|
|
1072
|
+
|
|
1073
|
+
<h3>Why these moments matter</h3>
|
|
1074
|
+
<p>
|
|
1075
|
+
A memory system that only saves at the end helps future sessions, but it cannot prevent the current agent from making a bad move. Eagle Mem splits behavior by timing: recall at start, search on prompt, guard before action, record after action, summarize at stop, and clean up at session end.
|
|
1076
|
+
</p>
|
|
1077
|
+
</div>
|
|
1078
|
+
</section>
|
|
1079
|
+
|
|
1080
|
+
<section class="section" id="agent-adapter">
|
|
1081
|
+
<div class="section-inner">
|
|
1082
|
+
<p class="section-number">06 / Technical Architecture</p>
|
|
1083
|
+
<h2>The Agent Adapter Layer</h2>
|
|
1084
|
+
<p class="lead">
|
|
1085
|
+
The project is agent-generic below the adapter layer. Claude Code and Codex have different config files, tool names, transcript formats, and output expectations. Eagle Mem normalizes those differences into one internal shape.
|
|
1086
|
+
</p>
|
|
1087
|
+
|
|
1088
|
+
<div class="grid-2">
|
|
1089
|
+
<article class="adapter-rule">
|
|
1090
|
+
<h3>Claude Code adapter</h3>
|
|
1091
|
+
<p>Registered through <code>~/.claude/settings.json</code>. Uses Claude hook events such as <code>SessionStart</code>, <code>PreToolUse</code>, <code>PostToolUse</code>, <code>Stop</code>, <code>SessionEnd</code>, <code>TaskCreated</code>, and <code>TaskCompleted</code>.</p>
|
|
1092
|
+
<div class="tag-row">
|
|
1093
|
+
<span class="tag">Bash</span>
|
|
1094
|
+
<span class="tag">Read</span>
|
|
1095
|
+
<span class="tag">Edit</span>
|
|
1096
|
+
<span class="tag">Write</span>
|
|
1097
|
+
<span class="tag">TaskCreate</span>
|
|
1098
|
+
</div>
|
|
1099
|
+
</article>
|
|
1100
|
+
|
|
1101
|
+
<article class="adapter-rule">
|
|
1102
|
+
<h3>Codex adapter</h3>
|
|
1103
|
+
<p>Registered through <code>~/.codex/hooks.json</code> after enabling <code>codex_hooks</code>. Shell protection covers current Codex shell tool paths, including <code>exec_command</code>, <code>shell_command</code>, and <code>unified_exec</code>.</p>
|
|
1104
|
+
<div class="tag-row">
|
|
1105
|
+
<span class="tag">exec_command</span>
|
|
1106
|
+
<span class="tag">unified_exec</span>
|
|
1107
|
+
<span class="tag">apply_patch</span>
|
|
1108
|
+
<span class="tag">Edit</span>
|
|
1109
|
+
<span class="tag">Write</span>
|
|
1110
|
+
</div>
|
|
1111
|
+
</article>
|
|
1112
|
+
</div>
|
|
1113
|
+
|
|
1114
|
+
<h3>Normalization rules</h3>
|
|
1115
|
+
<table>
|
|
1116
|
+
<thead>
|
|
1117
|
+
<tr>
|
|
1118
|
+
<th>Problem</th>
|
|
1119
|
+
<th>Normalization</th>
|
|
1120
|
+
<th>Result</th>
|
|
1121
|
+
</tr>
|
|
1122
|
+
</thead>
|
|
1123
|
+
<tbody>
|
|
1124
|
+
<tr>
|
|
1125
|
+
<td>Each agent names tools differently.</td>
|
|
1126
|
+
<td><code>eagle_is_shell_tool</code> treats known shell tool names as the same category.</td>
|
|
1127
|
+
<td>Release boundaries and RTK token guard work across agents.</td>
|
|
1128
|
+
</tr>
|
|
1129
|
+
<tr>
|
|
1130
|
+
<td>Each agent identifies sessions differently.</td>
|
|
1131
|
+
<td>Hooks parse <code>session_id</code>, <code>cwd</code>, transcript path, workspace paths, and agent-specific markers.</td>
|
|
1132
|
+
<td>Rows attach to the correct project and session.</td>
|
|
1133
|
+
</tr>
|
|
1134
|
+
<tr>
|
|
1135
|
+
<td>Agent output must look different.</td>
|
|
1136
|
+
<td><code>eagle_emit_context_for_agent</code> can keep Codex compact and user-clean while Claude receives richer hook context.</td>
|
|
1137
|
+
<td>The same memory is useful without flooding the UI.</td>
|
|
1138
|
+
</tr>
|
|
1139
|
+
<tr>
|
|
1140
|
+
<td>Future agents may only support some hook moments.</td>
|
|
1141
|
+
<td>The system treats each hook as additive. Missing hooks reduce features but do not invalidate the core database model.</td>
|
|
1142
|
+
<td>New adapters can start small and grow toward full support.</td>
|
|
1143
|
+
</tr>
|
|
1144
|
+
</tbody>
|
|
1145
|
+
</table>
|
|
1146
|
+
|
|
1147
|
+
<div class="callout">
|
|
1148
|
+
<h3>The adapter contract</h3>
|
|
1149
|
+
<p>Any future agent can become an Eagle Mem participant if it can run local scripts at lifecycle moments, pass JSON or structured context through stdin, accept context or block decisions from stdout, and preserve a project working directory. Full support needs five moments: start, prompt, before tool, after tool, and stop.</p>
|
|
1150
|
+
</div>
|
|
1151
|
+
</div>
|
|
1152
|
+
</section>
|
|
1153
|
+
|
|
1154
|
+
<section class="section" id="database">
|
|
1155
|
+
<div class="section-inner">
|
|
1156
|
+
<p class="section-number">07 / Technical Architecture</p>
|
|
1157
|
+
<h2>The Database Layer</h2>
|
|
1158
|
+
<p class="lead">
|
|
1159
|
+
The database is the shared memory. It is intentionally boring: one local SQLite file, WAL mode, FTS5 search tables, and small normalized records. This keeps the system portable and avoids a background service.
|
|
1160
|
+
</p>
|
|
1161
|
+
|
|
1162
|
+
<div class="diagram-frame" role="img" aria-labelledby="db-map-title db-map-desc">
|
|
1163
|
+
<svg class="diagram" viewBox="0 0 1100 620" xmlns="http://www.w3.org/2000/svg">
|
|
1164
|
+
<title id="db-map-title">Eagle Mem database architecture</title>
|
|
1165
|
+
<desc id="db-map-desc">A database diagram showing sessions, summaries, observations, code chunks, agent artifacts, features, pending verification, guardrails, and orchestration lanes.</desc>
|
|
1166
|
+
<defs>
|
|
1167
|
+
<marker id="arrow2" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
|
|
1168
|
+
<path d="M0,0 L0,6 L9,3 z" fill="#111111"></path>
|
|
1169
|
+
</marker>
|
|
1170
|
+
</defs>
|
|
1171
|
+
|
|
1172
|
+
<rect x="40" y="48" width="190" height="82" class="box-cyan"></rect>
|
|
1173
|
+
<text x="62" y="78">sessions</text>
|
|
1174
|
+
<text x="62" y="101" class="small">one row per agent run</text>
|
|
1175
|
+
|
|
1176
|
+
<rect x="310" y="48" width="190" height="82" class="box"></rect>
|
|
1177
|
+
<text x="332" y="78">summaries</text>
|
|
1178
|
+
<text x="332" y="101" class="small">request, learned, completed</text>
|
|
1179
|
+
|
|
1180
|
+
<rect x="570" y="48" width="190" height="82" class="box-soft"></rect>
|
|
1181
|
+
<text x="592" y="78">observations</text>
|
|
1182
|
+
<text x="592" y="101" class="small">tool calls, files, output size</text>
|
|
1183
|
+
|
|
1184
|
+
<rect x="830" y="48" width="190" height="82" class="box-yellow"></rect>
|
|
1185
|
+
<text x="852" y="78">overviews</text>
|
|
1186
|
+
<text x="852" y="101" class="small">project briefing</text>
|
|
1187
|
+
|
|
1188
|
+
<rect x="40" y="210" width="190" height="82" class="box"></rect>
|
|
1189
|
+
<text x="62" y="240">code_chunks</text>
|
|
1190
|
+
<text x="62" y="263" class="small">indexed source excerpts</text>
|
|
1191
|
+
|
|
1192
|
+
<rect x="310" y="210" width="190" height="82" class="box-green"></rect>
|
|
1193
|
+
<text x="332" y="240">agent_artifacts</text>
|
|
1194
|
+
<text x="332" y="263" class="small">memories, plans, tasks</text>
|
|
1195
|
+
|
|
1196
|
+
<rect x="570" y="210" width="190" height="82" class="box-yellow"></rect>
|
|
1197
|
+
<text x="592" y="240">features</text>
|
|
1198
|
+
<text x="592" y="263" class="small">files, deps, smoke tests</text>
|
|
1199
|
+
|
|
1200
|
+
<rect x="830" y="210" width="190" height="82" class="box-soft"></rect>
|
|
1201
|
+
<text x="852" y="240">pending_verify</text>
|
|
1202
|
+
<text x="852" y="263" class="small">release blockers</text>
|
|
1203
|
+
|
|
1204
|
+
<rect x="40" y="372" width="190" height="82" class="box-soft"></rect>
|
|
1205
|
+
<text x="62" y="402">guardrails</text>
|
|
1206
|
+
<text x="62" y="425" class="small">file rules and warnings</text>
|
|
1207
|
+
|
|
1208
|
+
<rect x="310" y="372" width="190" height="82" class="box"></rect>
|
|
1209
|
+
<text x="332" y="402">command_rules</text>
|
|
1210
|
+
<text x="332" y="425" class="small">learned shell handling</text>
|
|
1211
|
+
|
|
1212
|
+
<rect x="570" y="372" width="190" height="82" class="box-cyan"></rect>
|
|
1213
|
+
<text x="592" y="402">file_hints</text>
|
|
1214
|
+
<text x="592" y="425" class="small">hot files and co-edits</text>
|
|
1215
|
+
|
|
1216
|
+
<rect x="830" y="372" width="190" height="82" class="box-green"></rect>
|
|
1217
|
+
<text x="852" y="402">orchestration</text>
|
|
1218
|
+
<text x="852" y="425" class="small">lanes, workers, handoffs</text>
|
|
1219
|
+
|
|
1220
|
+
<path d="M230,88 L305,88" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1221
|
+
<path d="M230,88 C318,150 480,150 570,88" stroke="#111111" stroke-width="3" fill="none" marker-end="url(#arrow2)"></path>
|
|
1222
|
+
<path d="M665,292 L665,366" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1223
|
+
<path d="M760,252 L825,252" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1224
|
+
<path d="M405,292 L405,366" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1225
|
+
<path d="M135,292 L135,366" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1226
|
+
<path d="M760,412 L825,412" stroke="#111111" stroke-width="3" marker-end="url(#arrow2)"></path>
|
|
1227
|
+
</svg>
|
|
1228
|
+
</div>
|
|
1229
|
+
|
|
1230
|
+
<h3>What each table family answers</h3>
|
|
1231
|
+
<table>
|
|
1232
|
+
<thead>
|
|
1233
|
+
<tr>
|
|
1234
|
+
<th>Table Family</th>
|
|
1235
|
+
<th>Question It Answers</th>
|
|
1236
|
+
<th>Used By</th>
|
|
1237
|
+
</tr>
|
|
1238
|
+
</thead>
|
|
1239
|
+
<tbody>
|
|
1240
|
+
<tr>
|
|
1241
|
+
<td><code>sessions</code>, <code>summaries</code>, <code>summaries_fts</code></td>
|
|
1242
|
+
<td>What happened before? What did the agent learn? What should the next agent remember?</td>
|
|
1243
|
+
<td>SessionStart, UserPromptSubmit, search CLI, Stop</td>
|
|
1244
|
+
</tr>
|
|
1245
|
+
<tr>
|
|
1246
|
+
<td><code>observations</code></td>
|
|
1247
|
+
<td>What files and commands were actually used during sessions?</td>
|
|
1248
|
+
<td>PostToolUse, curator, search session drill-down</td>
|
|
1249
|
+
</tr>
|
|
1250
|
+
<tr>
|
|
1251
|
+
<td><code>overviews</code></td>
|
|
1252
|
+
<td>What is this project, in a concise briefing?</td>
|
|
1253
|
+
<td>SessionStart, overview CLI, scan</td>
|
|
1254
|
+
</tr>
|
|
1255
|
+
<tr>
|
|
1256
|
+
<td><code>code_chunks</code>, <code>code_chunks_fts</code></td>
|
|
1257
|
+
<td>Which source files look relevant to this prompt?</td>
|
|
1258
|
+
<td>UserPromptSubmit, index CLI</td>
|
|
1259
|
+
</tr>
|
|
1260
|
+
<tr>
|
|
1261
|
+
<td><code>agent_memories</code>, <code>agent_plans</code>, <code>agent_tasks</code></td>
|
|
1262
|
+
<td>What durable agent artifacts should be shared across Claude Code and Codex?</td>
|
|
1263
|
+
<td>PostToolUse, SessionEnd, skills, search CLI</td>
|
|
1264
|
+
</tr>
|
|
1265
|
+
<tr>
|
|
1266
|
+
<td><code>features</code>, <code>feature_files</code>, <code>feature_dependencies</code>, <code>feature_smoke_tests</code></td>
|
|
1267
|
+
<td>Which user-facing behavior is connected to a file or dependency?</td>
|
|
1268
|
+
<td>PostToolUse, PreToolUse, feature CLI</td>
|
|
1269
|
+
</tr>
|
|
1270
|
+
<tr>
|
|
1271
|
+
<td><code>pending_feature_verifications</code></td>
|
|
1272
|
+
<td>Which affected features still need smoke testing before release?</td>
|
|
1273
|
+
<td>PreToolUse release blocks, Stop reconciliation, feature verify/waive</td>
|
|
1274
|
+
</tr>
|
|
1275
|
+
<tr>
|
|
1276
|
+
<td><code>orchestrations</code>, <code>orchestration_lanes</code>, worker tables</td>
|
|
1277
|
+
<td>Who owns each lane, what is blocked, and what validation is required?</td>
|
|
1278
|
+
<td>orchestrate CLI, SessionStart task injection, worker handoffs</td>
|
|
1279
|
+
</tr>
|
|
1280
|
+
</tbody>
|
|
1281
|
+
</table>
|
|
1282
|
+
</div>
|
|
1283
|
+
</section>
|
|
1284
|
+
|
|
1285
|
+
<section class="section" id="recall">
|
|
1286
|
+
<div class="section-inner">
|
|
1287
|
+
<p class="section-number">08 / Technical Architecture</p>
|
|
1288
|
+
<h2>Recall Flow</h2>
|
|
1289
|
+
<p class="lead">
|
|
1290
|
+
Recall is the "start warm" feature. It gives the agent the right memory at the right time without dumping months of history into every prompt.
|
|
1291
|
+
</p>
|
|
1292
|
+
|
|
1293
|
+
<div class="step-list">
|
|
1294
|
+
<article class="step">
|
|
1295
|
+
<div class="step-num">A</div>
|
|
1296
|
+
<div>
|
|
1297
|
+
<h3>Build project identity</h3>
|
|
1298
|
+
<p>The hook normalizes the current project from workspace paths, transcripts, remembered session markers, or the current working directory. This prevents worktrees and resumed sessions from becoming separate memories by accident.</p>
|
|
1299
|
+
</div>
|
|
1300
|
+
</article>
|
|
1301
|
+
<article class="step">
|
|
1302
|
+
<div class="step-num">B</div>
|
|
1303
|
+
<div>
|
|
1304
|
+
<h3>Load high-signal context</h3>
|
|
1305
|
+
<p>SessionStart creates the visible "Recall Ready" banner, then adds overview, recent summaries, stored memories, tasks, code index stats, and hot files when available.</p>
|
|
1306
|
+
</div>
|
|
1307
|
+
</article>
|
|
1308
|
+
<article class="step">
|
|
1309
|
+
<div class="step-num">C</div>
|
|
1310
|
+
<div>
|
|
1311
|
+
<h3>Search only when useful</h3>
|
|
1312
|
+
<p>UserPromptSubmit ignores tiny prompts with fewer than three words. For real prompts, it extracts useful search terms, searches summaries and code chunks, and returns compact relevant recall.</p>
|
|
1313
|
+
</div>
|
|
1314
|
+
</article>
|
|
1315
|
+
<article class="step">
|
|
1316
|
+
<div class="step-num">D</div>
|
|
1317
|
+
<div>
|
|
1318
|
+
<h3>Save what happened</h3>
|
|
1319
|
+
<p>Stop persists summary data immediately using explicit fields or heuristics, then enrichment can improve the record later without delaying the user's session.</p>
|
|
1320
|
+
</div>
|
|
1321
|
+
</article>
|
|
1322
|
+
</div>
|
|
1323
|
+
|
|
1324
|
+
<h3>Recall is not the same as enforcement</h3>
|
|
1325
|
+
<p>
|
|
1326
|
+
Recall helps the agent know what happened before. Enforcement stops risky actions. A strong architecture needs both. Eagle Mem uses FTS5 recall for context and feature verification for release safety.
|
|
1327
|
+
</p>
|
|
1328
|
+
</div>
|
|
1329
|
+
</section>
|
|
1330
|
+
|
|
1331
|
+
<section class="section" id="guardrails">
|
|
1332
|
+
<div class="section-inner">
|
|
1333
|
+
<p class="section-number">09 / Technical Architecture</p>
|
|
1334
|
+
<h2>Guardrail Flow</h2>
|
|
1335
|
+
<p class="lead">
|
|
1336
|
+
Guardrails are timed around risk. Reading a file is low risk, so Eagle Mem surfaces decisions and feature context after reads. Editing and release commands are high risk, so Eagle Mem checks before or immediately after those actions.
|
|
1337
|
+
</p>
|
|
1338
|
+
|
|
1339
|
+
<div class="diagram-frame" role="img" aria-labelledby="guardrail-title guardrail-desc">
|
|
1340
|
+
<svg class="diagram" viewBox="0 0 1100 520" xmlns="http://www.w3.org/2000/svg">
|
|
1341
|
+
<title id="guardrail-title">Eagle Mem feature verification flow</title>
|
|
1342
|
+
<desc id="guardrail-desc">A flow from edit to pending feature verification, then release boundary block, then verify or waive.</desc>
|
|
1343
|
+
<defs>
|
|
1344
|
+
<marker id="arrow3" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
|
|
1345
|
+
<path d="M0,0 L0,6 L9,3 z" fill="#111111"></path>
|
|
1346
|
+
</marker>
|
|
1347
|
+
</defs>
|
|
1348
|
+
|
|
1349
|
+
<rect x="50" y="80" width="190" height="86" class="box"></rect>
|
|
1350
|
+
<text x="72" y="112">Agent edits file</text>
|
|
1351
|
+
<text x="72" y="136" class="small">Edit, Write, apply_patch</text>
|
|
1352
|
+
|
|
1353
|
+
<rect x="300" y="80" width="210" height="86" class="box-yellow"></rect>
|
|
1354
|
+
<text x="322" y="112">PostToolUse</text>
|
|
1355
|
+
<text x="322" y="136" class="small">find feature impacts</text>
|
|
1356
|
+
|
|
1357
|
+
<rect x="570" y="80" width="230" height="86" class="box-cyan"></rect>
|
|
1358
|
+
<text x="592" y="112">pending verification</text>
|
|
1359
|
+
<text x="592" y="136" class="small">feature + file + fingerprint</text>
|
|
1360
|
+
|
|
1361
|
+
<rect x="860" y="80" width="190" height="86" class="box"></rect>
|
|
1362
|
+
<text x="882" y="112">Release command</text>
|
|
1363
|
+
<text x="882" y="136" class="small">git push, gh pr create, publish</text>
|
|
1364
|
+
|
|
1365
|
+
<rect x="860" y="250" width="190" height="88" class="box-soft"></rect>
|
|
1366
|
+
<text x="882" y="282">PreToolUse block</text>
|
|
1367
|
+
<text x="882" y="306" class="small">show smoke tests</text>
|
|
1368
|
+
|
|
1369
|
+
<rect x="570" y="250" width="230" height="88" class="box-green"></rect>
|
|
1370
|
+
<text x="592" y="282">Verify or waive</text>
|
|
1371
|
+
<text x="592" y="306" class="small">feature verify / waive</text>
|
|
1372
|
+
|
|
1373
|
+
<rect x="300" y="250" width="210" height="88" class="box-cyan"></rect>
|
|
1374
|
+
<text x="322" y="282">Release allowed</text>
|
|
1375
|
+
<text x="322" y="306" class="small">no pending rows for diff</text>
|
|
1376
|
+
|
|
1377
|
+
<path d="M240,123 L295,123" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1378
|
+
<path d="M510,123 L565,123" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1379
|
+
<path d="M800,123 L855,123" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1380
|
+
<path d="M955,166 L955,244" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1381
|
+
<path d="M860,294 L805,294" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1382
|
+
<path d="M570,294 L515,294" stroke="#111111" stroke-width="3" marker-end="url(#arrow3)"></path>
|
|
1383
|
+
</svg>
|
|
1384
|
+
</div>
|
|
1385
|
+
|
|
1386
|
+
<h3>Guardrail types</h3>
|
|
1387
|
+
<table>
|
|
1388
|
+
<thead>
|
|
1389
|
+
<tr>
|
|
1390
|
+
<th>Guardrail</th>
|
|
1391
|
+
<th>Trigger</th>
|
|
1392
|
+
<th>User Experience</th>
|
|
1393
|
+
</tr>
|
|
1394
|
+
</thead>
|
|
1395
|
+
<tbody>
|
|
1396
|
+
<tr>
|
|
1397
|
+
<td>Decision recall</td>
|
|
1398
|
+
<td>Reading a file with past decisions</td>
|
|
1399
|
+
<td>The agent sees a note like "Do not revert without explicit user request."</td>
|
|
1400
|
+
</tr>
|
|
1401
|
+
<tr>
|
|
1402
|
+
<td>Stale memory check</td>
|
|
1403
|
+
<td>Editing a file that may contradict stored memory</td>
|
|
1404
|
+
<td>The agent is told to update memory if the edit makes old context wrong.</td>
|
|
1405
|
+
</tr>
|
|
1406
|
+
<tr>
|
|
1407
|
+
<td>Feature guardrail</td>
|
|
1408
|
+
<td>Reading or editing a file mapped to a feature</td>
|
|
1409
|
+
<td>The agent sees dependencies, related files, last verification, and smoke tests.</td>
|
|
1410
|
+
</tr>
|
|
1411
|
+
<tr>
|
|
1412
|
+
<td>Release boundary block</td>
|
|
1413
|
+
<td><code>git push</code>, <code>gh pr create</code>, or package publish with pending verification</td>
|
|
1414
|
+
<td>The command is denied with exact verification or waiver instructions.</td>
|
|
1415
|
+
</tr>
|
|
1416
|
+
<tr>
|
|
1417
|
+
<td>Token guard</td>
|
|
1418
|
+
<td>Shell commands likely to dump large raw output</td>
|
|
1419
|
+
<td>The command is rewritten through RTK or blocked with a compact alternative.</td>
|
|
1420
|
+
</tr>
|
|
1421
|
+
</tbody>
|
|
1422
|
+
</table>
|
|
1423
|
+
</div>
|
|
1424
|
+
</section>
|
|
1425
|
+
|
|
1426
|
+
<section class="section" id="lanes">
|
|
1427
|
+
<div class="section-inner">
|
|
1428
|
+
<p class="section-number">10 / Technical Architecture</p>
|
|
1429
|
+
<h2>Worker Lanes For Multi-Agent Work</h2>
|
|
1430
|
+
<p class="lead">
|
|
1431
|
+
Lanes are the architecture for work that is too wide for one agent turn. Instead of one agent keeping a fragile mental checklist, Eagle Mem stores lane ownership and status in SQLite so another agent can continue after compaction or handoff.
|
|
1432
|
+
</p>
|
|
1433
|
+
|
|
1434
|
+
<div class="grid-3">
|
|
1435
|
+
<article class="concept">
|
|
1436
|
+
<h3>Coordinator</h3>
|
|
1437
|
+
<p>The active agent defines the goal, splits independent lanes, avoids duplicate work, integrates results, and runs final validation.</p>
|
|
1438
|
+
</article>
|
|
1439
|
+
<article class="concept">
|
|
1440
|
+
<h3>Worker</h3>
|
|
1441
|
+
<p>A worker owns one bounded lane. It usually runs in a git worktree and should not rewrite another worker's files or revert unrelated edits.</p>
|
|
1442
|
+
</article>
|
|
1443
|
+
<article class="concept">
|
|
1444
|
+
<h3>Durable State</h3>
|
|
1445
|
+
<p>Lane records include owner, target agent, status, worktree path, validation command, notes, and handoff output.</p>
|
|
1446
|
+
</article>
|
|
1447
|
+
</div>
|
|
1448
|
+
|
|
1449
|
+
<h3>Default routing</h3>
|
|
1450
|
+
<p>
|
|
1451
|
+
Eagle Mem can route broad work to the opposite agent by default. A Codex coordinator can spawn Claude Code workers; a Claude Code coordinator can spawn Codex workers. The goal is not to make agents compete. The goal is to let each lane have one owner and one validation path.
|
|
1452
|
+
</p>
|
|
1453
|
+
|
|
1454
|
+
<pre><code># Agent-run protocol, not usually a user task
|
|
1455
|
+
eagle-mem orchestrate init "Ship the release safely"
|
|
1456
|
+
eagle-mem orchestrate lane add api --agent codex --desc "Routes and tests" --validate "npm test"
|
|
1457
|
+
eagle-mem orchestrate spawn api
|
|
1458
|
+
eagle-mem orchestrate sync
|
|
1459
|
+
eagle-mem orchestrate handoff --write docs/handoff-context.md</code></pre>
|
|
1460
|
+
|
|
1461
|
+
<h3>Why lanes matter for all agents</h3>
|
|
1462
|
+
<p>
|
|
1463
|
+
Context windows end. Tools fail. A user may switch from Claude Code to Codex. A worker may finish while the coordinator is compacted. Lanes make this survivable because the state is outside any one transcript.
|
|
1464
|
+
</p>
|
|
1465
|
+
</div>
|
|
1466
|
+
</section>
|
|
1467
|
+
|
|
1468
|
+
<section class="section" id="ux-principles">
|
|
1469
|
+
<div class="section-inner">
|
|
1470
|
+
<p class="section-number">11 / UX Architecture</p>
|
|
1471
|
+
<h2>The UX Philosophy</h2>
|
|
1472
|
+
<p class="lead">
|
|
1473
|
+
Eagle Mem's UX is not a large screen. It is a set of small, timely interventions inside the agent's existing workflow. The best UX here is often invisible: the user notices that the agent remembers, avoids mistakes, and coordinates work, but does not need to babysit a new interface.
|
|
1474
|
+
</p>
|
|
1475
|
+
|
|
1476
|
+
<div class="grid-2">
|
|
1477
|
+
<article class="principle">
|
|
1478
|
+
<h3>1. Stay in the agent's flow</h3>
|
|
1479
|
+
<p>Users already live in Claude Code or Codex. Eagle Mem should not require them to open a dashboard before every task. Hooks inject context where the agent already is.</p>
|
|
1480
|
+
</article>
|
|
1481
|
+
<article class="principle">
|
|
1482
|
+
<h3>2. Show up only when useful</h3>
|
|
1483
|
+
<p>SessionStart gives a compact status. Prompt recall appears only for meaningful prompts. Release blocks happen only when current changed files map to pending feature verification.</p>
|
|
1484
|
+
</article>
|
|
1485
|
+
<article class="principle">
|
|
1486
|
+
<h3>3. Teach the agent, not just the user</h3>
|
|
1487
|
+
<p>Most messages are addressed to the agent because the agent is the actor about to read, edit, push, or spawn work. The user benefits from better behavior without extra manual steps.</p>
|
|
1488
|
+
</article>
|
|
1489
|
+
<article class="principle">
|
|
1490
|
+
<h3>4. Keep trust local</h3>
|
|
1491
|
+
<p>The database is local. Logs and memory are local. There is no hosted memory service. This is important for repo privacy and for agent adoption across many project types.</p>
|
|
1492
|
+
</article>
|
|
1493
|
+
<article class="principle">
|
|
1494
|
+
<h3>5. Be explicit at risk boundaries</h3>
|
|
1495
|
+
<p>When a release command is blocked, the message must say exactly why, which features are pending, what smoke tests to run, and how to verify or waive.</p>
|
|
1496
|
+
</article>
|
|
1497
|
+
<article class="principle">
|
|
1498
|
+
<h3>6. Respect each agent's display model</h3>
|
|
1499
|
+
<p>Claude can handle richer hook context. Codex should keep user-facing replies clean and let Stop capture summaries from normal prose.</p>
|
|
1500
|
+
</article>
|
|
1501
|
+
</div>
|
|
1502
|
+
</div>
|
|
1503
|
+
</section>
|
|
1504
|
+
|
|
1505
|
+
<section class="section" id="ux-surfaces">
|
|
1506
|
+
<div class="section-inner">
|
|
1507
|
+
<p class="section-number">12 / UX Architecture</p>
|
|
1508
|
+
<h2>User-Facing Surfaces</h2>
|
|
1509
|
+
<p class="lead">
|
|
1510
|
+
Eagle Mem has many small surfaces. Each one has a specific UX job. Together, they make memory feel automatic instead of heavy.
|
|
1511
|
+
</p>
|
|
1512
|
+
|
|
1513
|
+
<div class="grid-2">
|
|
1514
|
+
<article class="surface">
|
|
1515
|
+
<h3>Install Screen</h3>
|
|
1516
|
+
<p><strong>Job:</strong> Build confidence. It checks prerequisites, shows what was installed, and explains when manual statusline patching is needed.</p>
|
|
1517
|
+
<p><strong>Failure to avoid:</strong> Silent partial setup where hooks are not actually active.</p>
|
|
1518
|
+
</article>
|
|
1519
|
+
|
|
1520
|
+
<article class="surface">
|
|
1521
|
+
<h3>Recall Ready Banner</h3>
|
|
1522
|
+
<p><strong>Job:</strong> Confirm memory is active at session start and show useful counts: sessions, sources, memories, tasks, code chunks, and last work.</p>
|
|
1523
|
+
<p><strong>Failure to avoid:</strong> Long startup dumps that cost tokens and bury the user's prompt.</p>
|
|
1524
|
+
</article>
|
|
1525
|
+
|
|
1526
|
+
<article class="surface">
|
|
1527
|
+
<h3>Relevant Recall</h3>
|
|
1528
|
+
<p><strong>Job:</strong> Give the agent enough past context to act correctly. It should be short, attributed, and directly relevant to the current prompt.</p>
|
|
1529
|
+
<p><strong>Failure to avoid:</strong> Treating memory search output as the final answer.</p>
|
|
1530
|
+
</article>
|
|
1531
|
+
|
|
1532
|
+
<article class="surface">
|
|
1533
|
+
<h3>Relevant Code</h3>
|
|
1534
|
+
<p><strong>Job:</strong> Point the agent to likely source files without pretending those snippets replace reading the actual code.</p>
|
|
1535
|
+
<p><strong>Failure to avoid:</strong> Making stale code index hits sound authoritative when current code has not been opened.</p>
|
|
1536
|
+
</article>
|
|
1537
|
+
|
|
1538
|
+
<article class="surface">
|
|
1539
|
+
<h3>Feature Block</h3>
|
|
1540
|
+
<p><strong>Job:</strong> Stop release commands when affected features still need verification. The message is a safety gate, not a suggestion.</p>
|
|
1541
|
+
<p><strong>Failure to avoid:</strong> Blocking without telling the user how to unblock safely.</p>
|
|
1542
|
+
</article>
|
|
1543
|
+
|
|
1544
|
+
<article class="surface">
|
|
1545
|
+
<h3>Token Guard</h3>
|
|
1546
|
+
<p><strong>Job:</strong> Prevent huge raw shell output from consuming context. It suggests an RTK equivalent and allows a short-lived escape hatch.</p>
|
|
1547
|
+
<p><strong>Failure to avoid:</strong> Making routine exploration feel broken. The replacement command must be clear.</p>
|
|
1548
|
+
</article>
|
|
1549
|
+
|
|
1550
|
+
<article class="surface">
|
|
1551
|
+
<h3>Statusline</h3>
|
|
1552
|
+
<p><strong>Job:</strong> Keep Eagle Mem visible in a tiny terminal footprint: version, session count, memory count, and turn count.</p>
|
|
1553
|
+
<p><strong>Failure to avoid:</strong> Turning the terminal into a dashboard that competes with coding.</p>
|
|
1554
|
+
</article>
|
|
1555
|
+
|
|
1556
|
+
<article class="surface">
|
|
1557
|
+
<h3>Skills</h3>
|
|
1558
|
+
<p><strong>Job:</strong> Teach agents when to search memory, manage tasks, build overviews, or coordinate lanes. Skills are UX for the agent's behavior.</p>
|
|
1559
|
+
<p><strong>Failure to avoid:</strong> Asking the user to run internal orchestration steps that the agent should run.</p>
|
|
1560
|
+
</article>
|
|
1561
|
+
</div>
|
|
1562
|
+
</div>
|
|
1563
|
+
</section>
|
|
1564
|
+
|
|
1565
|
+
<section class="section" id="tutorial">
|
|
1566
|
+
<div class="section-inner">
|
|
1567
|
+
<p class="section-number">13 / Tutorial</p>
|
|
1568
|
+
<h2>Walkthrough: From Empty Memory To Safer Release</h2>
|
|
1569
|
+
<p class="lead">
|
|
1570
|
+
This walkthrough explains how the system feels to a beginner. The same flow works whether the active agent is Claude Code or Codex.
|
|
1571
|
+
</p>
|
|
1572
|
+
|
|
1573
|
+
<div class="step-list">
|
|
1574
|
+
<article class="step">
|
|
1575
|
+
<div class="step-num">1</div>
|
|
1576
|
+
<div>
|
|
1577
|
+
<h3>Install once</h3>
|
|
1578
|
+
<p>The user installs Eagle Mem. The installer sets up hooks, migrations, skills, config, and optional statusline integration. After that, the user opens their normal agent in a project.</p>
|
|
1579
|
+
<pre><code>npm install -g eagle-mem
|
|
1580
|
+
eagle-mem install</code></pre>
|
|
1581
|
+
</div>
|
|
1582
|
+
</article>
|
|
1583
|
+
|
|
1584
|
+
<article class="step">
|
|
1585
|
+
<div class="step-num">2</div>
|
|
1586
|
+
<div>
|
|
1587
|
+
<h3>Start a session</h3>
|
|
1588
|
+
<p>SessionStart runs automatically. On a new project, background scan and index jobs can create a project overview and searchable source chunks. On an existing project, the agent sees compact recall.</p>
|
|
1589
|
+
</div>
|
|
1590
|
+
</article>
|
|
1591
|
+
|
|
1592
|
+
<article class="step">
|
|
1593
|
+
<div class="step-num">3</div>
|
|
1594
|
+
<div>
|
|
1595
|
+
<h3>Ask a normal question</h3>
|
|
1596
|
+
<p>The user asks, "Can you fix the release guardrail bug?" UserPromptSubmit turns that into an FTS5 query, finds relevant prior summaries and code chunks, and injects only the useful context.</p>
|
|
1597
|
+
</div>
|
|
1598
|
+
</article>
|
|
1599
|
+
|
|
1600
|
+
<article class="step">
|
|
1601
|
+
<div class="step-num">4</div>
|
|
1602
|
+
<div>
|
|
1603
|
+
<h3>The agent reads and edits files</h3>
|
|
1604
|
+
<p>PostToolUse records observations. If a file belongs to a tracked feature, Eagle Mem can create pending verification records tied to the feature, file, and current diff fingerprint.</p>
|
|
1605
|
+
</div>
|
|
1606
|
+
</article>
|
|
1607
|
+
|
|
1608
|
+
<article class="step">
|
|
1609
|
+
<div class="step-num">5</div>
|
|
1610
|
+
<div>
|
|
1611
|
+
<h3>The agent tries to release</h3>
|
|
1612
|
+
<p>If the agent runs <code>git push</code>, <code>gh pr create</code>, or package publish while affected features are pending, PreToolUse blocks the command and tells the agent what must be verified.</p>
|
|
1613
|
+
</div>
|
|
1614
|
+
</article>
|
|
1615
|
+
|
|
1616
|
+
<article class="step">
|
|
1617
|
+
<div class="step-num">6</div>
|
|
1618
|
+
<div>
|
|
1619
|
+
<h3>Verification resolves the blocker</h3>
|
|
1620
|
+
<p>After smoke tests pass, the agent runs <code>eagle-mem feature verify <name> --notes "what passed"</code>. If the exception is intentional, it can waive a specific pending record with a reason.</p>
|
|
1621
|
+
</div>
|
|
1622
|
+
</article>
|
|
1623
|
+
|
|
1624
|
+
<article class="step">
|
|
1625
|
+
<div class="step-num">7</div>
|
|
1626
|
+
<div>
|
|
1627
|
+
<h3>The turn ends with durable memory</h3>
|
|
1628
|
+
<p>Stop saves what happened so the next session can recall it. Codex can keep the final reply clean; Claude can use richer summary fields when appropriate. Either way, the durable memory lands in SQLite.</p>
|
|
1629
|
+
</div>
|
|
1630
|
+
</article>
|
|
1631
|
+
</div>
|
|
1632
|
+
|
|
1633
|
+
<h3>What beginners should remember</h3>
|
|
1634
|
+
<ul>
|
|
1635
|
+
<li><strong>You do not have to open a dashboard.</strong> Work normally in your agent.</li>
|
|
1636
|
+
<li><strong>You do not have to manually search first.</strong> The hook searches when your prompt has enough signal.</li>
|
|
1637
|
+
<li><strong>You do have to verify real feature risk.</strong> If Eagle Mem blocks release, run the relevant smoke tests, then verify or waive with notes.</li>
|
|
1638
|
+
<li><strong>You can ask agents to use lanes for broad work.</strong> The agent should run the orchestration commands and keep the user updated.</li>
|
|
1639
|
+
</ul>
|
|
1640
|
+
</div>
|
|
1641
|
+
</section>
|
|
1642
|
+
|
|
1643
|
+
<section class="section" id="future-agents">
|
|
1644
|
+
<div class="section-inner">
|
|
1645
|
+
<p class="section-number">14 / All-Agent Applicability</p>
|
|
1646
|
+
<h2>How To Add Another Agent</h2>
|
|
1647
|
+
<p class="lead">
|
|
1648
|
+
The project already supports Claude Code and Codex, but the architecture should scale to any coding agent that can run local hooks or wrapper scripts. The integration work should live at the edge, not inside the database model.
|
|
1649
|
+
</p>
|
|
1650
|
+
|
|
1651
|
+
<h3>Minimum viable adapter</h3>
|
|
1652
|
+
<table>
|
|
1653
|
+
<thead>
|
|
1654
|
+
<tr>
|
|
1655
|
+
<th>Capability</th>
|
|
1656
|
+
<th>Needed For</th>
|
|
1657
|
+
<th>Fallback If Missing</th>
|
|
1658
|
+
</tr>
|
|
1659
|
+
</thead>
|
|
1660
|
+
<tbody>
|
|
1661
|
+
<tr>
|
|
1662
|
+
<td>Session start hook</td>
|
|
1663
|
+
<td>Inject overview, summaries, memories, tasks, and code hints.</td>
|
|
1664
|
+
<td>User can run <code>eagle-mem search</code> manually, but warm start is weaker.</td>
|
|
1665
|
+
</tr>
|
|
1666
|
+
<tr>
|
|
1667
|
+
<td>User prompt hook</td>
|
|
1668
|
+
<td>Search memory in response to the current request.</td>
|
|
1669
|
+
<td>Agent can use the search skill manually.</td>
|
|
1670
|
+
</tr>
|
|
1671
|
+
<tr>
|
|
1672
|
+
<td>Pre-tool hook</td>
|
|
1673
|
+
<td>Block releases, enforce guardrails, and rewrite noisy commands before context damage.</td>
|
|
1674
|
+
<td>Post-action warnings still work, but safety is weaker.</td>
|
|
1675
|
+
</tr>
|
|
1676
|
+
<tr>
|
|
1677
|
+
<td>Post-tool hook</td>
|
|
1678
|
+
<td>Record observations, mirror tasks, and create pending feature verification records.</td>
|
|
1679
|
+
<td>Stop summaries can still save high-level memory, but tool history is thin.</td>
|
|
1680
|
+
</tr>
|
|
1681
|
+
<tr>
|
|
1682
|
+
<td>Stop hook</td>
|
|
1683
|
+
<td>Persist session summaries and learned decisions automatically.</td>
|
|
1684
|
+
<td>Manual <code>eagle-mem session save</code> can capture summaries.</td>
|
|
1685
|
+
</tr>
|
|
1686
|
+
</tbody>
|
|
1687
|
+
</table>
|
|
1688
|
+
|
|
1689
|
+
<h3>Adapter checklist</h3>
|
|
1690
|
+
<ol>
|
|
1691
|
+
<li>Register the agent's lifecycle events to call the installed scripts in <code>~/.eagle-mem/hooks/</code>.</li>
|
|
1692
|
+
<li>Set <code>EAGLE_AGENT_SOURCE</code> to a stable value, such as <code>codex</code>, <code>claude-code</code>, or a future agent key.</li>
|
|
1693
|
+
<li>Map the agent's shell and file tools into Eagle Mem's known categories.</li>
|
|
1694
|
+
<li>Pass enough JSON to identify <code>session_id</code>, <code>cwd</code>, tool name, tool input, and optional transcript path.</li>
|
|
1695
|
+
<li>Teach output formatting for the agent: compact JSON, plain additional context, or deny decisions.</li>
|
|
1696
|
+
<li>Install the same skills or equivalent instruction files so the agent knows when to search, orchestrate, verify, or summarize.</li>
|
|
1697
|
+
<li>Store all rows with source attribution so shared memory can say which agent created the knowledge.</li>
|
|
1698
|
+
</ol>
|
|
1699
|
+
|
|
1700
|
+
<div class="callout">
|
|
1701
|
+
<h3>Architectural rule for new agents</h3>
|
|
1702
|
+
<p>Do not fork the memory model for every agent. Add a thin adapter, normalize into the same hook contract, and keep shared behavior in <code>lib/</code> and <code>db/</code>. Agent-specific behavior should explain how to speak to the agent, not redefine what memory means.</p>
|
|
1703
|
+
</div>
|
|
1704
|
+
</div>
|
|
1705
|
+
</section>
|
|
1706
|
+
|
|
1707
|
+
<section class="section" id="source-map">
|
|
1708
|
+
<div class="section-inner">
|
|
1709
|
+
<p class="section-number">15 / Source Map</p>
|
|
1710
|
+
<h2>Where To Read The Code</h2>
|
|
1711
|
+
<p class="lead">
|
|
1712
|
+
Use this map when you want to verify the tutorial against the implementation. Start with the row that matches your question.
|
|
1713
|
+
</p>
|
|
1714
|
+
|
|
1715
|
+
<div class="source-list">
|
|
1716
|
+
<article class="source-box">
|
|
1717
|
+
<h3>Product promise and public explanation</h3>
|
|
1718
|
+
<ul>
|
|
1719
|
+
<li><code>README.md</code> - product layers, getting started, hook table, token savings, anti-regression, lanes.</li>
|
|
1720
|
+
<li><code>package.json</code> - version, package entrypoint, published file set, project keywords.</li>
|
|
1721
|
+
</ul>
|
|
1722
|
+
</article>
|
|
1723
|
+
|
|
1724
|
+
<article class="source-box">
|
|
1725
|
+
<h3>CLI entrypoints</h3>
|
|
1726
|
+
<ul>
|
|
1727
|
+
<li><code>bin/eagle-mem</code> - subcommand dispatcher.</li>
|
|
1728
|
+
<li><code>scripts/help.sh</code> - user-facing command map.</li>
|
|
1729
|
+
<li><code>scripts/search.sh</code>, <code>scripts/feature.sh</code>, <code>scripts/orchestrate.sh</code> - main user and agent command surfaces.</li>
|
|
1730
|
+
</ul>
|
|
1731
|
+
</article>
|
|
1732
|
+
|
|
1733
|
+
<article class="source-box">
|
|
1734
|
+
<h3>Installation and adapters</h3>
|
|
1735
|
+
<ul>
|
|
1736
|
+
<li><code>scripts/install.sh</code> - runtime copy, migrations, hook registration, skills, statusline, config.</li>
|
|
1737
|
+
<li><code>lib/codex-hooks.sh</code> - Codex hook enablement and hook registration.</li>
|
|
1738
|
+
<li><code>lib/hooks.sh</code> - Claude Code hook patching.</li>
|
|
1739
|
+
</ul>
|
|
1740
|
+
</article>
|
|
1741
|
+
|
|
1742
|
+
<article class="source-box">
|
|
1743
|
+
<h3>Hook behavior</h3>
|
|
1744
|
+
<ul>
|
|
1745
|
+
<li><code>hooks/session-start.sh</code> and <code>lib/hooks-sessionstart.sh</code> - warm start, auto-scan, auto-index, auto-prune, auto-curate.</li>
|
|
1746
|
+
<li><code>hooks/user-prompt-submit.sh</code> - context pressure, prompt search, relevant recall and code hits.</li>
|
|
1747
|
+
<li><code>hooks/pre-tool-use.sh</code> - release blocking and token guard.</li>
|
|
1748
|
+
<li><code>hooks/post-tool-use.sh</code> and <code>lib/hooks-posttool.sh</code> - observations, mirrored artifacts, feature impacts, stale hints.</li>
|
|
1749
|
+
<li><code>hooks/stop.sh</code> and <code>hooks/session-end.sh</code> - summary persistence and cleanup.</li>
|
|
1750
|
+
</ul>
|
|
1751
|
+
</article>
|
|
1752
|
+
|
|
1753
|
+
<article class="source-box">
|
|
1754
|
+
<h3>Shared runtime and data</h3>
|
|
1755
|
+
<ul>
|
|
1756
|
+
<li><code>lib/common.sh</code> - project detection, agent detection, command parsing, redaction, release command detection.</li>
|
|
1757
|
+
<li><code>lib/db-core.sh</code> and <code>lib/db.sh</code> - SQLite connection setup and module loading.</li>
|
|
1758
|
+
<li><code>lib/db-features.sh</code> - feature lookup, pending verification, verify/waive behavior.</li>
|
|
1759
|
+
<li><code>db/*.sql</code> - schema and migrations for all persistent state.</li>
|
|
1760
|
+
</ul>
|
|
1761
|
+
</article>
|
|
1762
|
+
|
|
1763
|
+
<article class="source-box">
|
|
1764
|
+
<h3>Agent instruction UX</h3>
|
|
1765
|
+
<ul>
|
|
1766
|
+
<li><code>skills/eagle-mem-search/SKILL.md</code> - when and how agents should search memory.</li>
|
|
1767
|
+
<li><code>skills/eagle-mem-orchestrate/SKILL.md</code> - coordinator and worker lane rules.</li>
|
|
1768
|
+
<li><code>skills/eagle-mem-tasks/SKILL.md</code> - task loop behavior for long sequential work.</li>
|
|
1769
|
+
</ul>
|
|
1770
|
+
</article>
|
|
1771
|
+
</div>
|
|
1772
|
+
|
|
1773
|
+
<h3>Recommended reading order</h3>
|
|
1774
|
+
<ol>
|
|
1775
|
+
<li>Read <code>README.md</code> for the product promise.</li>
|
|
1776
|
+
<li>Read <code>scripts/install.sh</code> to understand activation.</li>
|
|
1777
|
+
<li>Read the hook scripts in lifecycle order.</li>
|
|
1778
|
+
<li>Read <code>lib/common.sh</code> and <code>lib/db-features.sh</code> for cross-agent normalization and safety gates.</li>
|
|
1779
|
+
<li>Read the migrations in <code>db/</code> to understand persistent state.</li>
|
|
1780
|
+
<li>Read the skills to understand how Eagle Mem shapes agent behavior.</li>
|
|
1781
|
+
</ol>
|
|
1782
|
+
</div>
|
|
1783
|
+
</section>
|
|
1784
|
+
|
|
1785
|
+
<div class="footer-note">
|
|
1786
|
+
<p>Built as a self-contained HTML tutorial for the Eagle Mem repo. Open <code>architecture.html</code> directly in a browser, or publish it as the site architecture page referenced by the README.</p>
|
|
1787
|
+
</div>
|
|
1788
|
+
</main>
|
|
1789
|
+
</div>
|
|
1790
|
+
</body>
|
|
1791
|
+
</html>
|