memtrails 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] — 2026-11-02
+
+- `gather(q, { notes: true })`: the same model call also writes what the kept memories say that answers the question,
+  every instance with its date and only what they state, reading all 80 candidates at once. Shown before the
+  memories, LoCoMo 79.5 → 80.9 (Mem0 76.5);
+  `bench/locomo.ts --gather 40 --notes` reproduces it.
+
 ## [0.2.0] — 2026-11-01
 
 - Consolidation reads "last week" as the seven days before it was said, and the calendar line names the last weekend

package/README.md

@@ -41,7 +41,7 @@ await memory.close();
   against 50.3% for plain search, and most of a cross-encoder reranker's gain, in about 3 ms on one CPU thread.
 - **Measured, honestly.** On all 1,307 held-out LoCoMo questions with 6,000 characters to read, memtrails alone on a
   CPU scores 77.4 (strict judge) against Mem0's 76.5 — a tie, reported as one; with `gather` reading what search
-  found, 79.5 — ahead beyond chance. [Benchmarks](docs/BENCHMARKS.md).
+  found and noting what it says, 80.9 — ahead beyond chance. [Benchmarks](docs/BENCHMARKS.md).
 - **Explorable.** A concept graph links what records share — people, places, systems, names — so an agent can walk
   from what it found to what a search for the words does not find.
 - **Built for agents.** `memory.tools()` gives `memory_search`, `memory_open` and `memory_explore` with zod and JSON
@@ -189,15 +189,17 @@ the [API reference](docs/API.md), and [what was tried and why](docs/RESEARCH.md)
 
 | | memtrails | Mem0 | Graphiti |
 |---|---|---|---|
-| LoCoMo, all 1,307 held-out questions, 6,000 characters, strict judge, `gather` at 40 | **79.5** | 76.5 | — |
-| the same, Mem0's own lenient judge | **91.4** | 87.8 | — |
+| LoCoMo, all 1,307 held-out questions, 6,000 characters, strict judge, `gather` at 40 with notes | **80.9** | 76.5 | — |
+| the same, Mem0's own lenient judge | **91.9** | 87.8 | — |
+| the same, `gather` without notes, strict / lenient | 79.5 / 91.4 | 76.5 / 87.8 | — |
 | the same with `search` alone, no model when searching, strict / lenient | 77.4 / 89.3 | 76.5 / 87.8 | — |
 | LoCoMo, 1,307 held-out questions, 28,000 characters, one search¹ | 79.9 | 80.6 | 42.1 |
 | LoCoMo, the same with an agent using each system's own tools¹ | **79.0** | 77.1 | 47.0 |
 | LongMemEval-S retrieval, strict all sessions @5 (467)² | **96.15** | — | — |
 
-The same reader and judges for every system. With `gather` (a model reads what search found and keeps what the answer
-needs) memtrails leads Mem0 beyond chance: +110/−71 questions strict (p 0.005), +78/−32 lenient. With `search` alone,
+The same reader and judges for every system. With `gather` (a model reads what search found, keeps what the answer
+needs and notes what it says) memtrails leads Mem0 beyond chance: +113/−55 questions strict, +78/−25 lenient (both
+p < 0.001). With `search` alone,
 the small-room and one-search comparisons are ties; the agent lead is
 small and was judged once. ¹ An earlier build (2026-10-27). ² gbrain-evals publishes 95.96 on the same count: a tie. [Full results, protocol and limitations](docs/BENCHMARKS.md).
 

package/dist/core/gather.d.ts

@@ -7,6 +7,9 @@ export interface Gathered {
     kept: string[];
     /** The searches the model asked for. */
     searches: string[];
+    /** With `notes`: what the kept memories say that answers the question, a few short lines (empty otherwise). Show them
+     *  before the memories, as notes on them: on LoCoMo this took 79.5 to 80.9 (docs/BENCHMARKS.md). */
+    notes: string[];
 }
 /** `from`/`to`: the time the question asks about ("on 10 April 2022", "in October 2023"). What happened then is searched
  *  for besides everything else and read first — not instead: a question also names dates it only counts from ("as of
@@ -14,4 +17,5 @@ export interface Gathered {
 export declare function memoryGather(d: RecallDeps, q: SearchQuery, o: {
     ask?: Ask;
     limit?: number;
+    notes?: boolean;
 }): Promise<Gathered>;

package/dist/core/gather.js

@@ -20,6 +20,9 @@ import { memorySearch, MAX_SEARCH } from './recall.js';
 import { cut } from './text.js';
 /** Candidates the model reads in one ask. */
 const PART = 40;
+/** With notes, all of them in one ask, so a question's notes are written once: on LoCoMo the same accuracy as two parts
+ *  of 40 (80.9 against 80.6), at 58% of the cost and 2.9 s against 7.5 s median. */
+const NOTES_PART = 80;
 /** Searches it may ask for. */
 const MORE = 6;
 const SYSTEM = `You pick, from someone's memories, every one needed to answer their question.
@@ -40,6 +43,19 @@ const SCHEMA = {
         searches: { type: 'array', items: { type: 'string' } },
     },
 };
+/** With notes: the same reading also writes down what the kept memories say that answers the question, so a list spread
+ *  over many memories reaches the reader as one line. */
+const NOTES_RULE = `
+
+In "notes", write what the memories you kept say that answers the question, in a few short lines: every instance with
+its date as the memories give it ("Books Tim has read: Harry Potter (2023-08-02), The Name of the Wind (2023-08-11)"),
+names, numbers and words as written. Only what they state, as plain statements: never write that something is not said,
+not given, unclear or unknown — leave it out instead, since other memories may hold it — and never a guess. Leave notes
+empty when the memories you kept say nothing about it. In the language of the question.`;
+const NOTES_SCHEMA = {
+    type: 'object', additionalProperties: false, required: ['keep', 'searches', 'notes'],
+    properties: { ...SCHEMA.properties, notes: { type: 'array', items: { type: 'string' } } },
+};
 const day = (ts) => (ts ? new Date(ts).toISOString().slice(0, 10) : '');
 /** One candidate as the model reads it: when it happened (from when to when, for what lasted) and when it was told, its
  *  text, and the passage that matched. */
@@ -49,25 +65,29 @@ function line(h, n) {
     const text = h.kind === 'observation' ? h.summary : `${h.title} — ${cut(h.summary, h.kind === 'profile' ? PROFILE_SHOWN : 600)}`;
     return `[m${n}] (${when}) ${text}${h.match ? `\n    … ${cut(h.match, 600)}` : ''}`;
 }
-async function pick(ask, question, list) {
+async function pick(ask, question, list, notes = false) {
     const parts = [];
-    for (let i = 0; i < list.length; i += PART)
-        parts.push(list.slice(i, i + PART));
+    const size = notes ? NOTES_PART : PART;
+    for (let i = 0; i < list.length; i += size)
+        parts.push(list.slice(i, i + size));
     const answers = await Promise.all(parts.map(async (part) => {
         const prompt = `Question: ${question}\n\nMemories:\n${part.map((h, n) => line(h, n + 1)).join('\n')}`;
         const a = await ask({
-            purpose: 'memory', system: SYSTEM, prompt: redactString(prompt), schema: SCHEMA,
-            name: 'memory_gather', maxTokens: 40 * part.length + 600, timeoutMs: 120_000, consequence: 'so these memories are kept unread',
+            purpose: 'memory', system: notes ? SYSTEM + NOTES_RULE : SYSTEM, prompt: redactString(prompt),
+            schema: (notes ? NOTES_SCHEMA : SCHEMA),
+            name: 'memory_gather', maxTokens: 40 * part.length + (notes ? 1400 : 600), timeoutMs: 120_000, consequence: 'so these memories are kept unread',
         });
         if (!('answer' in a))
-            return { keep: part.map((h) => h.id), searches: [] };
+            return { keep: part.map((h) => h.id), searches: [], notes: [] };
         const got = a.answer;
         const ids = Array.isArray(got.keep) ? got.keep.filter((x) => typeof x === 'string') : [];
         const keep = ids.map((x) => part[Number(x.replace(/^m/, '')) - 1]?.id).filter((x) => !!x);
         const searches = Array.isArray(got.searches) ? got.searches.filter((x) => typeof x === 'string' && !!x.trim()) : [];
-        return { keep, searches };
+        const said = notes && Array.isArray(got.notes) ? got.notes.filter((x) => typeof x === 'string' && !!x.trim()).map((x) => redactString(x.trim())) : [];
+        return { keep, searches, notes: said };
     }));
-    return { keep: new Set(answers.flatMap((a) => a.keep)), searches: [...new Set(answers.flatMap((a) => a.searches.map((s) => s.trim())))] };
+    return { keep: new Set(answers.flatMap((a) => a.keep)), searches: [...new Set(answers.flatMap((a) => a.searches.map((s) => s.trim())))],
+        notes: answers.flatMap((a) => a.notes) };
 }
 /** `from`/`to`: the time the question asks about ("on 10 April 2022", "in October 2023"). What happened then is searched
  *  for besides everything else and read first — not instead: a question also names dates it only counts from ("as of
@@ -79,7 +99,7 @@ export async function memoryGather(d, q, o) {
     const [inDates, wide] = await Promise.all([from || to ? memorySearch(d, { ...q, limit }) : [], memorySearch(d, { ...open, limit })]);
     const dated = new Set(inDates.map((h) => h.id));
     const first = [...inDates, ...wide.filter((h) => !dated.has(h.id))];
-    const one = await pick(ask, q.query, first);
+    const one = await pick(ask, q.query, first, o.notes);
     const searches = one.searches.slice(0, MORE);
     const have = new Set(first.map((h) => h.id));
     const more = [];
@@ -90,9 +110,9 @@ export async function memoryGather(d, q, o) {
                 more.push(h);
             }
     }
-    const two = more.length ? await pick(ask, q.query, more) : { keep: new Set(), searches: [] };
+    const two = more.length ? await pick(ask, q.query, more, o.notes) : { keep: new Set(), searches: [], notes: [] };
     const all = [...first, ...more];
     const kept = all.filter((h) => one.keep.has(h.id) || two.keep.has(h.id));
     const keptIds = new Set(kept.map((h) => h.id));
-    return { found: [...kept, ...all.filter((h) => !keptIds.has(h.id))], kept: kept.map((h) => h.id), searches };
+    return { found: [...kept, ...all.filter((h) => !keptIds.has(h.id))], kept: kept.map((h) => h.id), searches, notes: [...one.notes, ...two.notes] };
 }

package/dist/memory.d.ts

@@ -84,7 +84,9 @@ export interface Memory {
         limit?: number;
     }): Promise<Explored>;
     /** A set for a question that counts, lists or totals: a wide search, then the language model keeps every instance. */
-    gather(q: SearchQuery): Promise<Gathered>;
+    gather(q: SearchQuery, o?: {
+        notes?: boolean;
+    }): Promise<Gathered>;
     /** Read what was added since last time and keep typed knowledge, dated observations and kept episodes. Needs a
      *  language model. Returns how many windows were read. */
     consolidate(): Promise<ConsolidationReport>;

package/dist/memory.js

@@ -201,7 +201,7 @@ export async function openMemory(o) {
             return sources.length ? { ...p, sources } : p;
         },
         explore: (s) => memoryExplore(deps, s),
-        gather: (s) => memoryGather(deps, s, { ask, ...(s.limit ? { limit: s.limit } : {}) }),
+        gather: (s, g) => memoryGather(deps, s, { ask, ...(s.limit ? { limit: s.limit } : {}), ...(g?.notes ? { notes: true } : {}) }),
         async consolidate() {
             const worker = new Consolidator({ ...base, concurrency: o.concurrency ?? 4 });
             const total = { windows: 0, added: 0, merged: 0, updated: 0, superseded: 0, linked: 0, dropped: 0, episodes: 0, observed: 0, cued: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrails",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Retrieval and exploration for any text — e-mail, chat, notes, documents, news, commits, conversations. Searchable at once, on your own machine, in any language; optional consolidation into typed knowledge with a language model.",
   "keywords": [
     "retrieval",