@niwa-labs/memory 0.0.0-stage → 0.0.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/src/records.ts ADDED
@@ -0,0 +1,538 @@
1
+ /**
2
+ * The records entry of the memory module: what another plugin may import from it. The records the
3
+ * module writes, the shapes of a note and its source, and the typed references of its actions; no
4
+ * factory and nothing that runs.
5
+ *
6
+ * There is one memory module on a host, and every agent has a memory of its own in it, named by the
7
+ * agent's name. A caller bound to an agent reaches that agent's memory; the owner reaches every one.
8
+ */
9
+
10
+ import { z } from "zod";
11
+
12
+ import { Address, actionRef, record } from "@niwa-labs/core";
13
+ import { RequestId } from "@niwa-labs/requests/records";
14
+ import { AgentName, BriefingSectionInput, BriefingSectionOutput, SessionRefText, TurnAuthor } from "@niwa-labs/agent/records";
15
+
16
+ /** Whose memory: the name of the agent it belongs to. */
17
+ export const MemoryName = AgentName;
18
+ export type MemoryName = z.output<typeof MemoryName>;
19
+
20
+ /** The id of a note, `note-<hex>`: the module issues it. */
21
+ export const NoteId = z.string().regex(/^note-[0-9a-f]{8,16}$/, "a note is named `note-<hex>`");
22
+ export type NoteId = z.output<typeof NoteId>;
23
+
24
+ /**
25
+ * The directory a path names, written one way: absolute, with no `.`, `..`, doubled or trailing slash.
26
+ * A relative path names no directory, so it has none.
27
+ */
28
+ export function canonicalDirectory(path: string): string | undefined {
29
+ if (!path.startsWith("/")) return undefined;
30
+ const parts: string[] = [];
31
+ for (const part of path.split("/")) {
32
+ if (part === "" || part === ".") continue;
33
+ if (part === "..") parts.pop();
34
+ else parts.push(part);
35
+ }
36
+ return `/${parts.join("/")}`;
37
+ }
38
+
39
+ /** A directory as it is read back: already in its canonical form. */
40
+ const Directory = z.string().min(1).max(512);
41
+
42
+ /**
43
+ * The project a note holds for: the directory the project lives in, the key attached sessions carry. However
44
+ * it is spelled, it is the canonical form of the directory, so two spellings of one directory are one project.
45
+ */
46
+ export const Project = Directory.refine((path) => path.startsWith("/"), "a project is an absolute directory").transform((path) => canonicalDirectory(path) ?? path);
47
+
48
+ /** Whom a note is about: the owner himself, or the work. */
49
+ export const NoteAbout = z.enum(["owner", "work"]);
50
+ export type NoteAbout = z.output<typeof NoteAbout>;
51
+
52
+ /**
53
+ * Where a note comes from. `owner`: the owner said it to the memory himself. `inferred`: the writer
54
+ * concluded it. `session`: it was read in the transcript of a session, up to a locator. `record`: a
55
+ * record of the journal shows it.
56
+ */
57
+ export const NoteSource = z.discriminatedUnion("kind", [
58
+ z.object({ kind: z.literal("owner") }).strict(),
59
+ z.object({ kind: z.literal("inferred") }).strict(),
60
+ z
61
+ .object({ kind: z.literal("session"), session: SessionRefText, from: z.string().min(1).optional(), upto: z.string().min(1) })
62
+ .strict(),
63
+ z.object({ kind: z.literal("record"), record: z.string().min(1) }).strict(),
64
+ ]);
65
+ export type NoteSource = z.output<typeof NoteSource>;
66
+
67
+ /** The longest text of a note: one conclusion, said in a few sentences. */
68
+ export const NOTE_TEXT_MAX = 1_000;
69
+ /** The longest detail of a note: what backs it, kept home. */
70
+ export const NOTE_DETAIL_MAX = 4_000;
71
+
72
+ const NoteText = z.string().trim().min(1).max(NOTE_TEXT_MAX);
73
+ const NoteDetail = z.string().trim().min(1).max(NOTE_DETAIL_MAX);
74
+
75
+ /**
76
+ * A note was written. `text` is the conclusion, the part that may leave the memory; `detail` is what
77
+ * backs it and stays home. `by` is who wrote it, which never makes it the owner's word: only a source
78
+ * of `owner` written by the owner is.
79
+ */
80
+ export const NoteWritten = record(
81
+ "memory.note.written",
82
+ z.object({
83
+ memory: MemoryName,
84
+ note: NoteId,
85
+ text: NoteText,
86
+ detail: NoteDetail.optional(),
87
+ about: NoteAbout,
88
+ project: Project.optional(),
89
+ source: NoteSource,
90
+ by: TurnAuthor,
91
+ }),
92
+ );
93
+
94
+ /**
95
+ * A note was written again, in other words or from another source: the memory counts it as one more
96
+ * source of the note it holds, instead of keeping a second copy.
97
+ */
98
+ export const NoteCorroborated = record(
99
+ "memory.note.corroborated",
100
+ z.object({ memory: MemoryName, note: NoteId, source: NoteSource, by: TurnAuthor }),
101
+ );
102
+
103
+ /** The owner confirmed a note: it is his word from now on, until it is changed by someone else. */
104
+ export const NoteConfirmed = record("memory.note.confirmed", z.object({ memory: MemoryName, note: NoteId, by: Address }));
105
+
106
+ /**
107
+ * A note was corrected: its text (and detail) are these from now on. The new text is a claim of its own: the
108
+ * corrector is its only source, and a place in the top layer earned by the old text is not kept.
109
+ */
110
+ export const NoteCorrected = record(
111
+ "memory.note.corrected",
112
+ z.object({ memory: MemoryName, note: NoteId, text: NoteText, detail: NoteDetail.optional(), by: TurnAuthor }),
113
+ );
114
+
115
+ /** A note was taken back: its conclusion no longer holds. It stays in the history, never in an answer. */
116
+ export const NoteRetracted = record(
117
+ "memory.note.retracted",
118
+ z.object({ memory: MemoryName, note: NoteId, reason: z.string().min(1).optional(), by: TurnAuthor }),
119
+ );
120
+
121
+ /**
122
+ * A note was erased: its text is never shown again, nor searched, nor told. The journal is written once,
123
+ * so the record that first held the text is still there; a reader of the memory sees only that it was.
124
+ */
125
+ export const NoteErased = record("memory.note.erased", z.object({ memory: MemoryName, note: NoteId, by: TurnAuthor }));
126
+
127
+ /**
128
+ * A note was lifted into the top layer of its memory: what the agent is shown first, in its briefing and
129
+ * its prompt. A note lifted or dropped by hand stays where it was put: consolidation leaves it alone.
130
+ */
131
+ export const NoteLifted = record("memory.note.lifted", z.object({ memory: MemoryName, note: NoteId, by: TurnAuthor }));
132
+
133
+ /** A note was dropped from the top layer: it is no longer shown first, and still holds and is found. */
134
+ export const NoteDropped = record("memory.note.dropped", z.object({ memory: MemoryName, note: NoteId, by: TurnAuthor }));
135
+
136
+ /** The name of a page: lowercase words joined by `-`, `_`, `.` or `/`. */
137
+ export const PageName = z.string().regex(/^[a-z0-9][a-z0-9._/-]{0,127}$/, "a page is named with lowercase letters, digits, '.', '_', '-' or '/', at most 128");
138
+ export type PageName = z.output<typeof PageName>;
139
+
140
+ /** The largest text of a page, in bytes: what the journal still holds inline in a record. */
141
+ export const PAGE_TEXT_MAX_BYTES = 16 * 1024;
142
+
143
+ const PageText = z
144
+ .string()
145
+ .min(1)
146
+ .refine((text) => Buffer.byteLength(text, "utf8") <= PAGE_TEXT_MAX_BYTES, `a page holds at most ${String(PAGE_TEXT_MAX_BYTES)} bytes: split it`);
147
+
148
+ /**
149
+ * A page was written: a longer text a memory keeps under a name, such as what a project is and how it
150
+ * works. A page is written whole; each write is its next revision.
151
+ */
152
+ export const PageWritten = record(
153
+ "memory.page.written",
154
+ z.object({
155
+ memory: MemoryName,
156
+ page: PageName,
157
+ title: z.string().min(1).max(200),
158
+ text: PageText,
159
+ project: Project.optional(),
160
+ basedOn: z.number().int().nonnegative(),
161
+ revision: z.number().int().positive(),
162
+ by: TurnAuthor,
163
+ }),
164
+ { guard: {
165
+ group: "memory.page", key: data => JSON.stringify([data.memory, data.page]),
166
+ initial: () => 0,
167
+ admit: (revision, data) => data.basedOn === revision && data.revision === revision + 1
168
+ ? undefined : { code: "stale-page", reason: `the page ${data.page} is at revision ${revision}, not ${data.basedOn}: read it again` },
169
+ fold: (_revision, data) => data.revision,
170
+ } },
171
+ );
172
+
173
+ /** The id of a turn of an agent's inbox, as the agents module names it. */
174
+ const TurnId = z.string().regex(/^(msg|fact)-[0-9a-f]{6,16}$/);
175
+
176
+ /**
177
+ * The digest of a session attached to an agent was taken into its memory. The digest stays where it is,
178
+ * in the agent's inbox; the memory keeps where it is (`record`, `turn`), which session it tells of and from
179
+ * where up to where, and the project the session works in.
180
+ */
181
+ export const DigestTaken = record(
182
+ "memory.digest.taken",
183
+ z.object({
184
+ memory: MemoryName,
185
+ turn: TurnId,
186
+ record: z.string().min(1),
187
+ session: SessionRefText,
188
+ from: z.string().min(1).optional(),
189
+ upto: z.string().min(1),
190
+ project: Project.optional(),
191
+ }),
192
+ );
193
+
194
+ /**
195
+ * A note about the owner was wanted by another address, for a purpose: it leaves the memory only on the
196
+ * owner's own answer, which is asked for once for each revision of the note, each address and each purpose.
197
+ */
198
+ export const ShareWanted = record(
199
+ "memory.share.wanted",
200
+ z.object({ memory: MemoryName, note: NoteId, revision: z.number().int().positive(), for: Address, purpose: z.string().min(1) }),
201
+ );
202
+
203
+ /**
204
+ * Whether a note about the owner may leave the memory for an address: the owner's answer to the question
205
+ * (`request`), or his word given directly. An answer that is not the owner's own, such as one a resolver
206
+ * found, lets nothing leave: `reason` says so.
207
+ */
208
+ export const ShareAnswered = record(
209
+ "memory.share.answered",
210
+ z.object({
211
+ memory: MemoryName,
212
+ note: NoteId,
213
+ revision: z.number().int().positive(),
214
+ for: Address,
215
+ /** What the answer holds for: the purpose he was told. Without one it holds for every purpose, which only he says himself. */
216
+ purpose: z.string().min(1).optional(),
217
+ allowed: z.boolean(),
218
+ request: RequestId.optional(),
219
+ reason: z.enum(["not-the-owner", "unanswered"]).optional(),
220
+ }),
221
+ );
222
+
223
+ const consolidationGuard = {
224
+ group: "memory.consolidation",
225
+ key: (data: { memory: MemoryName }) => data.memory,
226
+ initial: (): string | null => null,
227
+ };
228
+
229
+ export const ConsolidationStarted = record("memory.consolidation.started", z.object({
230
+ memory: MemoryName,
231
+ operation: z.string().min(1),
232
+ }), { guard: {
233
+ ...consolidationGuard,
234
+ admit: active => active === null ? undefined : { code: "busy", reason: "a consolidation is already in progress" },
235
+ fold: (_active, data) => data.operation,
236
+ } });
237
+
238
+ /**
239
+ * A memory was consolidated: notes that say the same were merged into one, the notes that earned it were
240
+ * lifted into the top layer and the weakest dropped out of a part grown too long, and notes that went
241
+ * stale or did not fit were retired. A note put in or out of the top layer by hand is left where it is.
242
+ */
243
+ export const Consolidated = record(
244
+ "memory.consolidated",
245
+ z.object({
246
+ memory: MemoryName,
247
+ operation: z.string().min(1),
248
+ merged: z.array(z.object({ note: NoteId, into: NoteId })),
249
+ lifted: z.array(NoteId),
250
+ dropped: z.array(NoteId),
251
+ retired: z.array(NoteId),
252
+ }),
253
+ { guard: {
254
+ ...consolidationGuard,
255
+ admit: (active, data) => active === data.operation ? undefined : { code: "stale", reason: "the consolidation claim changed" },
256
+ fold: () => null,
257
+ } },
258
+ );
259
+
260
+ /** The record types the module declares. */
261
+ export const MEMORY_TYPES = [NoteWritten, NoteCorroborated, NoteConfirmed, NoteCorrected, NoteRetracted, NoteErased, NoteLifted, NoteDropped, PageWritten, DigestTaken, ShareWanted, ShareAnswered, ConsolidationStarted, Consolidated] as const;
262
+
263
+ /** Where a note stands. */
264
+ export const NoteStatus = z.enum(["live", "retracted", "merged", "retired", "erased"]);
265
+ export type NoteStatus = z.output<typeof NoteStatus>;
266
+
267
+ /** A note as the memory holds it at a position of the journal. */
268
+ export const NoteView = z.object({
269
+ memory: MemoryName,
270
+ note: NoteId,
271
+ /** Empty once the note is erased. */
272
+ text: z.string(),
273
+ detail: z.string().optional(),
274
+ about: NoteAbout,
275
+ project: Directory.optional(),
276
+ source: NoteSource,
277
+ by: TurnAuthor,
278
+ status: NoteStatus,
279
+ /** Whether the owner stands behind it: he wrote it as his word, confirmed it, or corrected it last. */
280
+ confirmed: z.boolean(),
281
+ /** How many sources it has: the same source, or the same writer's own conclusion, counts once. */
282
+ sources: z.number().int().positive(),
283
+ /** Whether it is in the top layer of its memory. */
284
+ top: z.boolean(),
285
+ /** Whether it was put in or out of the top layer by hand: consolidation leaves it where it is. */
286
+ pinned: z.boolean(),
287
+ /** How many times its text was written: 1, and one more for each correction. */
288
+ revision: z.number().int().positive(),
289
+ /** When the last record that changed it was written, in milliseconds since the epoch. */
290
+ changed: z.number().int().nonnegative(),
291
+ /** The position of the journal where it was written, and of the last record that changed it. */
292
+ written: z.number().int().nonnegative(),
293
+ seq: z.number().int().nonnegative(),
294
+ });
295
+ export type NoteView = z.output<typeof NoteView>;
296
+
297
+ /** A page as the memory holds it. */
298
+ export const PageView = z.object({
299
+ memory: MemoryName,
300
+ page: PageName,
301
+ title: z.string(),
302
+ text: z.string(),
303
+ project: Directory.optional(),
304
+ revision: z.number().int().positive(),
305
+ by: TurnAuthor,
306
+ /** The position of the journal where this revision was written. */
307
+ seq: z.number().int().nonnegative(),
308
+ });
309
+ export type PageView = z.output<typeof PageView>;
310
+
311
+ /** One thing a search found: a note, a page or the digest of a session, with where it stands in the journal. */
312
+ export const SearchHit = z.object({
313
+ kind: z.enum(["note", "page", "session"]),
314
+ /** The note's id, the page's name, or the turn that told the digest. */
315
+ id: z.string(),
316
+ /** The page's title, or the session a digest tells of; the text of a note, or the start of a longer text. */
317
+ title: z.string().optional(),
318
+ text: z.string(),
319
+ about: NoteAbout.optional(),
320
+ project: Directory.optional(),
321
+ score: z.number(),
322
+ seq: z.number().int().nonnegative(),
323
+ });
324
+ export type SearchHit = z.output<typeof SearchHit>;
325
+
326
+ /** The memory a call names. A caller bound to an agent may leave it out, or name its own. */
327
+ const Named = { memory: MemoryName.optional() };
328
+
329
+ /** A position of the journal: the memory as it was right after that record. */
330
+ const At = z.number().int().nonnegative();
331
+
332
+ export const memoryNote = actionRef("memory.note", {
333
+ description:
334
+ "Writes a note to a memory: one conclusion (`text`), what backs it (`detail`, kept home), whom it is about (the owner or the work), the project it holds for, and its source. An agent writes to its own memory; a source of `owner` is only the owner's to give. A note the memory already holds in the same words gains a source instead of a copy (`corroborated`).",
335
+ input: z.object({
336
+ ...Named,
337
+ text: NoteText,
338
+ detail: NoteDetail.optional(),
339
+ about: NoteAbout.default("work"),
340
+ project: Project.optional(),
341
+ source: NoteSource.default({ kind: "inferred" }),
342
+ }),
343
+ output: z.object({ memory: MemoryName, note: NoteId, corroborated: z.boolean() }),
344
+ });
345
+
346
+ export const memoryGet = actionRef("memory.get", {
347
+ description: "Gets one note of a memory, as it stands now or as it stood at a position of the journal (`at`).",
348
+ input: z.object({ ...Named, note: NoteId, at: At.optional() }),
349
+ output: NoteView,
350
+ });
351
+
352
+ export const memoryList = actionRef("memory.list", {
353
+ description:
354
+ "Lists the notes of a memory that hold now, or held at a position of the journal (`at`), newest first; with `project`, those of that project and the general ones.",
355
+ input: z.object({ ...Named, project: Project.optional(), about: NoteAbout.optional(), limit: z.number().int().positive().max(500).default(50), at: At.optional() }),
356
+ output: z.object({ memory: MemoryName, notes: z.array(NoteView) }),
357
+ });
358
+
359
+ export const memoryConfirm = actionRef("memory.confirm", {
360
+ description: "The owner confirms a note of a memory: it is his word from now on. Only the owner may.",
361
+ input: z.object({ memory: MemoryName, note: NoteId }),
362
+ output: z.object({ note: NoteId, confirmed: z.boolean() }),
363
+ });
364
+
365
+ export const memoryCorrect = actionRef("memory.correct", {
366
+ description:
367
+ "Corrects a note: its text (and detail) are these from now on. A correction by the owner is his word; one by the agent leaves the note unconfirmed. The new text has the corrector as its only source, and earns its place in the top layer again.",
368
+ input: z.object({ ...Named, note: NoteId, text: NoteText, detail: NoteDetail.optional() }),
369
+ output: z.object({ note: NoteId, revision: z.number().int().positive() }),
370
+ });
371
+
372
+ export const memoryRetract = actionRef("memory.retract", {
373
+ description: "Takes a note back: its conclusion no longer holds. It stays in the history and never reaches an answer again.",
374
+ input: z.object({ ...Named, note: NoteId, reason: z.string().min(1).optional() }),
375
+ output: z.object({ note: NoteId }),
376
+ });
377
+
378
+ export const memoryErase = actionRef("memory.erase", {
379
+ description:
380
+ "Erases a note: its text is never shown, searched or told again. Stronger than a retraction; an answer that once rested on it can no longer be read back.",
381
+ input: z.object({ ...Named, note: NoteId }),
382
+ output: z.object({ note: NoteId }),
383
+ });
384
+
385
+ export const memoryPageWrite = actionRef("memory.page.write", {
386
+ description:
387
+ "Writes a page of a memory whole: a longer text under a name, such as what a project is and how it works. Give the revision it was read at to refuse a write over a change made since.",
388
+ input: z.object({
389
+ ...Named,
390
+ page: PageName,
391
+ title: z.string().min(1).max(200),
392
+ text: PageText,
393
+ project: Project.optional(),
394
+ /** The revision the page was read at; 0 for a page that must be new. */
395
+ revision: z.number().int().nonnegative().optional(),
396
+ }),
397
+ output: z.object({ page: PageName, revision: z.number().int().positive() }),
398
+ });
399
+
400
+ export const memoryPageGet = actionRef("memory.page.get", {
401
+ description: "Gets a page of a memory, as it stands now or at a position of the journal (`at`).",
402
+ input: z.object({ ...Named, page: PageName, at: At.optional() }),
403
+ output: PageView,
404
+ });
405
+
406
+ /** What a page list shows of each page: where it stands, not its text. */
407
+ export const PageSummary = PageView.omit({ text: true });
408
+ export type PageSummary = z.output<typeof PageSummary>;
409
+
410
+ export const memoryPageList = actionRef("memory.page.list", {
411
+ description:
412
+ "Lists the pages of a memory as they stand now, by name: the title, the project, the revision and who wrote it, without the text. With `project`, those of that project and the general ones.",
413
+ input: z.object({ ...Named, project: Project.optional() }),
414
+ output: z.object({ memory: MemoryName, pages: z.array(PageSummary) }),
415
+ });
416
+
417
+ export const memorySearch = actionRef("memory.search", {
418
+ description:
419
+ "Searches a memory by words: the notes that hold, the pages and the digests of attached sessions, best first. With `project`, only what holds for that project and in general. Words match whole or as the start of a longer word; nothing leaves the host.",
420
+ input: z.object({
421
+ ...Named,
422
+ query: z.string().min(1).max(500),
423
+ project: Project.optional(),
424
+ limit: z.number().int().positive().max(50).default(10),
425
+ at: At.optional(),
426
+ }),
427
+ output: z.object({ memory: MemoryName, hits: z.array(SearchHit) }),
428
+ });
429
+
430
+ export const memoryLift = actionRef("memory.lift", {
431
+ description: "Lifts a note into the top layer of its memory: it is shown first, in the agent's briefing. Consolidation will not drop it.",
432
+ input: z.object({ ...Named, note: NoteId }),
433
+ output: z.object({ note: NoteId, top: z.boolean() }),
434
+ });
435
+
436
+ export const memoryDrop = actionRef("memory.drop", {
437
+ description:
438
+ "Drops a note from the top layer: it is no longer shown first, but still holds and is found by a search. Consolidation will not lift it again.",
439
+ input: z.object({ ...Named, note: NoteId }),
440
+ output: z.object({ note: NoteId, top: z.boolean() }),
441
+ });
442
+
443
+ export const memoryTop = actionRef("memory.top", {
444
+ description:
445
+ "The top layer of a memory for a project: the notes shown first, about the owner, for the project and in general, within the size the module allows.",
446
+ input: z.object({ ...Named, project: Project.optional() }),
447
+ output: z.object({ memory: MemoryName, text: z.string(), notes: z.array(NoteId), left: z.number().int().nonnegative() }),
448
+ });
449
+
450
+ /** The section of an agent's briefing the module writes: the top layer of its memory, for its project. */
451
+ export const memoryBrief = actionRef("memory.brief", {
452
+ description:
453
+ "The memory's section of an agent's briefing: the top layer of its memory for the project it works on (its own, or the directory of the session attached last).",
454
+ input: BriefingSectionInput,
455
+ output: BriefingSectionOutput,
456
+ });
457
+
458
+ /**
459
+ * Where a conclusion told by a memory comes from: whose memory it is (the data owner's address), the note,
460
+ * and the position of the journal it stood at, so a later look at an answer reads the memory as it was.
461
+ */
462
+ export const SourceRef = z.object({
463
+ owner: z.object({ kind: z.literal("agent"), id: MemoryName }),
464
+ note: NoteId,
465
+ seq: z.number().int().nonnegative(),
466
+ });
467
+ export type SourceRef = z.output<typeof SourceRef>;
468
+
469
+ /** One conclusion a context answer tells: its text, whom it is about and where it holds, and its source. */
470
+ export const ContextItem = z.object({
471
+ note: NoteId,
472
+ text: z.string(),
473
+ about: NoteAbout,
474
+ project: Directory.optional(),
475
+ /** What backs it: told only to the memory's own agent and to the owner. */
476
+ detail: z.string().optional(),
477
+ confirmed: z.boolean(),
478
+ source: SourceRef,
479
+ });
480
+ export type ContextItem = z.output<typeof ContextItem>;
481
+
482
+ /**
483
+ * A note about the owner that matched and did not leave, and why. A note of another project is not named at all:
484
+ * a reader learns nothing of what it may not read.
485
+ */
486
+ export const Withheld = z.object({
487
+ note: NoteId,
488
+ reason: z.enum(["about-the-owner"]),
489
+ /**
490
+ * The owner was asked and has not answered (`asked`), he said no (`refused`), or nobody asked him (`not-asked`):
491
+ * a read at a position asks nobody, and a note he was never asked of is not one he was asked of.
492
+ */
493
+ status: z.enum(["asked", "refused", "not-asked"]).optional(),
494
+ });
495
+ export type Withheld = z.output<typeof Withheld>;
496
+
497
+ export const memoryContext = actionRef("memory.context", {
498
+ description:
499
+ "Asks a memory for context: what it holds that bears on `query`, for an addressee and a purpose. Another agent is told only the conclusions with whom they are about and where they hold, never what backs them; a project's notes go to that project's agents and are not named to any other; the limit counts only the conclusions the addressee may be told; a note about the owner leaves only once the owner said yes for that addressee and purpose, and he is asked unless the request is read at a position (`at`), which asks nobody. Every conclusion carries its source: the memory's address, the note and the position of the journal; give `at` to read the memory as it stood then.",
500
+ input: z.object({
501
+ memory: MemoryName,
502
+ query: z.string().min(1).max(500),
503
+ purpose: z.string().min(1).max(500),
504
+ /** Whom the context is for. A caller bound to an address asks for itself; a handler names the addressee. */
505
+ for: Address.optional(),
506
+ project: Project.optional(),
507
+ limit: z.number().int().positive().max(20).default(5),
508
+ at: At.optional(),
509
+ }),
510
+ output: z.object({
511
+ memory: z.object({ kind: z.literal("agent"), id: MemoryName }),
512
+ for: Address,
513
+ /** The position of the journal the answer was read at. */
514
+ at: z.number().int().nonnegative(),
515
+ items: z.array(ContextItem),
516
+ withheld: z.array(Withheld),
517
+ }),
518
+ });
519
+
520
+ export const memoryShare = actionRef("memory.share", {
521
+ description:
522
+ "The owner says whether a note about him may leave a memory for an address, without being asked. Only the owner may; his word holds for the note as it is now, and for the `purpose` he names, or for every purpose when he names none.",
523
+ input: z.object({ memory: MemoryName, note: NoteId, for: Address, purpose: z.string().min(1).max(500).optional(), allowed: z.boolean() }),
524
+ output: z.object({ note: NoteId, allowed: z.boolean() }),
525
+ });
526
+
527
+ export const memoryConsolidate = actionRef("memory.consolidate", {
528
+ description:
529
+ "Consolidates a memory: merges notes that say the same, lifts into the top layer the notes the owner confirmed or that have enough sources, drops the weakest from a part of the top layer grown too long, and retires notes that went stale unconfirmed or do not fit. Notes placed by hand are left where they are.",
530
+ input: z.object({ ...Named }),
531
+ output: z.object({
532
+ memory: MemoryName,
533
+ merged: z.array(z.object({ note: NoteId, into: NoteId })),
534
+ lifted: z.array(NoteId),
535
+ dropped: z.array(NoteId),
536
+ retired: z.array(NoteId),
537
+ }),
538
+ });
package/src/same.ts ADDED
@@ -0,0 +1,15 @@
1
+ // When two texts say the same: they are the same sequence of words, whatever their case, spacing and
2
+ // punctuation. Nothing looser may stand for the same claim: a different order, number or negation says
3
+ // another thing, and a note's standing (the owner's word, how many sources back it) follows its claim.
4
+
5
+ /** The words of a text in order: letters and digits of any script, lowercased, none left out. */
6
+ function sequence(text: string): string[] {
7
+ return text.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
8
+ }
9
+
10
+ /** Whether two texts say the same: the same words in the same order. */
11
+ export function same(one: string, other: string): boolean {
12
+ const a = sequence(one);
13
+ const b = sequence(other);
14
+ return a.length > 0 && a.length === b.length && a.every((word, at) => word === b[at]);
15
+ }
package/src/search.ts ADDED
@@ -0,0 +1,48 @@
1
+ // Search by words, on the host: no model and no service. A text is cut into words, and a query word
2
+ // matches a word of a text that is the same or, for a word of four letters or more, starts with it
3
+ // ("deploy" finds "deploys" and "deployment"). Texts are ranked by BM25.
4
+
5
+ /** The words of a text: letters and digits of any script, lowercased; a word of one letter says nothing. */
6
+ export function words(text: string): string[] {
7
+ return (text.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).filter((word) => word.length > 1);
8
+ }
9
+
10
+ /** A text a search ranks, with what it answers when it is found. */
11
+ export interface Searchable<T> {
12
+ readonly text: string;
13
+ readonly value: T;
14
+ }
15
+
16
+ /** Whether a query word matches a word of a text. */
17
+ function matches(query: string, word: string): boolean {
18
+ return word === query || (query.length >= 4 && word.startsWith(query));
19
+ }
20
+
21
+ const K1 = 1.2;
22
+ const B = 0.75;
23
+
24
+ /** The texts that match any word of the query, best first, with their scores; at most `limit`. */
25
+ export function rank<T>(query: string, texts: readonly Searchable<T>[], limit: number): Array<{ value: T; score: number }> {
26
+ const wanted = [...new Set(words(query))];
27
+ if (wanted.length === 0 || texts.length === 0) return [];
28
+ const docs = texts.map((one) => words(one.text));
29
+ const average = docs.reduce((sum, doc) => sum + doc.length, 0) / docs.length || 1;
30
+ // How many texts hold each query word: a word most texts hold weighs little.
31
+ const holding = wanted.map((query) => docs.filter((doc) => doc.some((word) => matches(query, word))).length);
32
+ const scored: Array<{ value: T; score: number; order: number }> = [];
33
+ docs.forEach((doc, order) => {
34
+ let score = 0;
35
+ wanted.forEach((query, at) => {
36
+ const count = doc.filter((word) => matches(query, word)).length;
37
+ if (count === 0) return;
38
+ const held = holding[at] ?? 0;
39
+ const idf = Math.log(1 + (docs.length - held + 0.5) / (held + 0.5));
40
+ score += (idf * count * (K1 + 1)) / (count + K1 * (1 - B + (B * doc.length) / average));
41
+ });
42
+ const text = texts[order];
43
+ if (score > 0 && text !== undefined) scored.push({ value: text.value, score, order });
44
+ });
45
+ // The better score first; of two the same, the later text, which is the newer.
46
+ scored.sort((a, b) => b.score - a.score || b.order - a.order);
47
+ return scored.slice(0, limit).map(({ value, score }) => ({ value, score: Math.round(score * 1000) / 1000 }));
48
+ }
@@ -0,0 +1,27 @@
1
+ // The question a memory asks the owner before a note about him leaves it. It names the note and its revision, and the
2
+ // purpose the note was wanted for; it never holds the note's text, which anyone who can read the open requests would
3
+ // read with it. The owner's page shows the text through a read of the note that is checked when it is shown.
4
+
5
+ /** The name of the question a memory asks the owner before a note about him leaves. */
6
+ export const SHARE_QUESTION = "memory.share";
7
+
8
+ /** The note a share question is about: whose memory, which note, which revision of its text. */
9
+ export interface ShareReference {
10
+ readonly memory: string;
11
+ readonly note: string;
12
+ readonly revision: number;
13
+ }
14
+
15
+ /** The detail of the question: the note it is about and the purpose it was wanted for. */
16
+ export function shareDetail(reference: ShareReference, purpose: string): string {
17
+ return `Note ${reference.note} of the memory of ${reference.memory}, revision ${String(reference.revision)}.\nWanted to: ${purpose}`;
18
+ }
19
+
20
+ const DETAIL = /^Note (note-[0-9a-f]+) of the memory of (\S+), revision (\d+)\.\nWanted to: ([\s\S]*)$/;
21
+
22
+ /** The note and the purpose a share question's detail names, when it names them. */
23
+ export function shareReferenceOf(detail: string | undefined): { reference: ShareReference; purpose: string } | undefined {
24
+ const found = detail === undefined ? null : DETAIL.exec(detail);
25
+ if (found === null) return undefined;
26
+ return { reference: { note: found[1]!, memory: found[2]!, revision: Number(found[3]) }, purpose: found[4]! };
27
+ }
package/src/top.ts ADDED
@@ -0,0 +1,44 @@
1
+ // The top layer of a memory: the notes it shows first. For a project it holds the lifted notes about the
2
+ // owner, those for the project and those that hold in general, in that order and the newest first in
3
+ // each part, as many as fit in its size.
4
+
5
+ import { holds, holdsFor } from "./holds.ts";
6
+ import type { NoteView } from "./records.ts";
7
+
8
+ /** The top layer as it is shown: its text, the notes in it, and how many lifted notes did not fit. */
9
+ export interface TopLayer {
10
+ readonly text: string;
11
+ readonly notes: string[];
12
+ readonly left: number;
13
+ }
14
+
15
+ /** The top layer of the notes of one memory, for a project (none: the owner and what holds in general). */
16
+ export function topLayer(notes: readonly NoteView[], project: string | undefined, size: number): TopLayer {
17
+ const lifted = notes.filter((note) => holds(note) && note.top).reverse();
18
+ const parts: Array<{ heading: string; notes: NoteView[] }> = [
19
+ { heading: "About the owner:", notes: lifted.filter((note) => note.about === "owner" && holdsFor(note.project, project)) },
20
+ ...(project === undefined ? [] : [{ heading: `For ${project}:`, notes: lifted.filter((note) => note.about === "work" && note.project === project) }]),
21
+ { heading: "In general:", notes: lifted.filter((note) => note.about === "work" && note.project === undefined) },
22
+ ];
23
+ const lines: string[] = [];
24
+ const shown: string[] = [];
25
+ let length = -1;
26
+ let left = 0;
27
+ for (const part of parts) {
28
+ let headed = false;
29
+ for (const note of part.notes) {
30
+ const line = `- ${note.text} (${note.note})`;
31
+ const adds = line.length + 1 + (headed ? 0 : part.heading.length + 1);
32
+ if (length + adds > size) {
33
+ left += 1;
34
+ continue;
35
+ }
36
+ if (!headed) lines.push(part.heading);
37
+ headed = true;
38
+ lines.push(line);
39
+ shown.push(note.note);
40
+ length += adds;
41
+ }
42
+ }
43
+ return { text: lines.join("\n"), notes: shown, left };
44
+ }