memtrails 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.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
+  and each of the six days before, so "on Friday" is dated without counting. Dates had landed a week early.
+- Observations carry 2 to 4 cues (questions they answer, in the asker's words); search reads cues as their own channel
+  at a tenth of the dense weight. LoCoMo, all 1,307 held-out questions: multi-hop 50.6 → 55.2, all 77.2 → 77.4.
+- `gather` reads as many as `limit` asks for (it always read 200). At 40, for any question, the rooms it builds score
+  79.5 on LoCoMo against Mem0's 76.5 (+110/−71 per question); `bench/locomo.ts --gather 40` reproduces it.
+
 ## [0.1.0] — 2026-10-31
 
 First public release.

package/README.md

@@ -40,7 +40,8 @@ await memory.close();
   stored at one bit a number): on 2,011 benchmark questions the answer reached the reader in 53.1% of top-5 lists
   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.2 (strict judge) against Mem0's 76.5 — a tie, reported as one. [Benchmarks](docs/BENCHMARKS.md).
+  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).
 - **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
@@ -188,13 +189,16 @@ 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 | **77.2** (no server) | 76.5 | — |
-| the same, Mem0's own lenient judge | **89.3** | 87.8 | — |
+| 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 | — |
+| 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. The small-room and one-search comparisons are ties; the agent lead is
+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 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).
 
 ## Limitations

package/dist/core/consolidate.js

@@ -146,7 +146,7 @@ function observationItem(o, src) {
         engine: src.engine, session: src.session, cwd: src.cwd, where: src.title, ts: src.ts, firstTs: src.ts,
         title: cut(o.text, 100), summary: o.text, body: '', files: [], appliesWhen: '', confidence: 'stated', importance: 2,
         status: 'active', provenance: o.provenance, seen: 1, fingerprint: fingerprint('observation', o.text, o.eventAt),
-        cues: [], concepts: o.concepts, ...(o.eventAt ? { eventAt: o.eventAt } : {}),
+        cues: o.cues ?? [], concepts: o.concepts, ...(o.eventAt ? { eventAt: o.eventAt } : {}),
         ...(o.startAt ? { startAt: o.startAt } : {}), ...(o.endAt ? { endAt: o.endAt } : {}), phase: o.phase, ...(o.about ? { about: o.about } : {}),
         ...(o.origin ? { origin: o.origin } : {}),
     };

package/dist/core/episodes.d.ts

@@ -23,8 +23,10 @@ export declare const isConversation: (e: {
 }) => boolean;
 /** A record's body: what its key summarises, its chunks are cut from, and opening it shows — whole, never shortened. */
 export declare function episodeBody(e: Pick<ReadableRequest, 'request' | 'reply' | 'files'> & Partial<Pick<ReadableRequest, 'said' | 'steps' | 'engine'>>): string;
-/** For each day a request was made, the days a time said relatively that day means — yesterday, this week, last week,
- *  last month, last year (weeks start on Monday, UTC as the requests' times) — so the model reads "last week" off a line
- *  instead of counting: measured on LoCoMo, "last week" said on Thursday 6 July was written as the week of 3 July. */
+/** For each day a request was made, the days a time said relatively that day means — yesterday, the week before, the
+ *  last weekend, each of the six days before by name, this week, last month, last year (UTC as the requests' times) —
+ *  so the model reads "last week" or "on Friday" off a line instead of counting. "Last week" is the seven days before,
+ *  as people mean it, not the Monday-to-Sunday week before this one: measured on LoCoMo, the calendar week put events
+ *  said on a Sunday thirteen days back, a week early. */
 export declare function calendarOf(tss: number[]): string;
 export declare function renderForExtraction(e: ReadableRequest, n: number): string;

package/dist/core/episodes.js

@@ -17,19 +17,23 @@ export function episodeBody(e) {
         parts.push(`Files: ${e.files.join(', ')}`);
     return parts.join('\n');
 }
-/** For each day a request was made, the days a time said relatively that day means — yesterday, this week, last week,
- *  last month, last year (weeks start on Monday, UTC as the requests' times) — so the model reads "last week" off a line
- *  instead of counting: measured on LoCoMo, "last week" said on Thursday 6 July was written as the week of 3 July. */
+/** For each day a request was made, the days a time said relatively that day means — yesterday, the week before, the
+ *  last weekend, each of the six days before by name, this week, last month, last year (UTC as the requests' times) —
+ *  so the model reads "last week" or "on Friday" off a line instead of counting. "Last week" is the seven days before,
+ *  as people mean it, not the Monday-to-Sunday week before this one: measured on LoCoMo, the calendar week put events
+ *  said on a Sunday thirteen days back, a week early. */
 export function calendarOf(tss) {
     const DAY = 86_400_000;
     const iso = (t) => new Date(t).toISOString().slice(0, 10);
     const wd = (t) => new Date(t).toLocaleDateString('en-GB', { weekday: 'short', timeZone: 'UTC' });
     const days = [...new Set(tss.filter((t) => t > 0).map((t) => Math.floor(t / DAY) * DAY))].sort((a, b) => a - b);
     return days.map((d) => {
-        const monday = d - ((new Date(d).getUTCDay() + 6) % 7) * DAY;
         const dt = new Date(d);
+        const monday = d - ((dt.getUTCDay() + 6) % 7) * DAY;
+        const sunday = d - (dt.getUTCDay() === 0 ? 7 : dt.getUTCDay()) * DAY;
         const lastMonth = new Date(Date.UTC(dt.getUTCFullYear(), dt.getUTCMonth() - 1, 1)).toISOString().slice(0, 7);
-        return `- ${wd(d)} ${iso(d)}: yesterday ${wd(d - DAY)} ${iso(d - DAY)} · this week ${iso(monday)} to ${iso(monday + 6 * DAY)} · last week ${iso(monday - 7 * DAY)} to ${iso(monday - DAY)} · last month ${lastMonth} · last year ${dt.getUTCFullYear() - 1}`;
+        const before = [2, 3, 4, 5, 6, 7].map((n) => `${wd(d - n * DAY)} ${iso(d - n * DAY)}`).join(', ');
+        return `- ${wd(d)} ${iso(d)}: yesterday ${wd(d - DAY)} ${iso(d - DAY)} · the days before ${before} · last week (the week before) ${iso(d - 7 * DAY)} to ${iso(d - DAY)} · last weekend ${iso(sunday - DAY)} to ${iso(sunday)} · this week ${iso(monday)} to ${iso(monday + 6 * DAY)} · last month ${lastMonth} · last year ${dt.getUTCFullYear() - 1}`;
     }).join('\n');
 }
 export function renderForExtraction(e, n) {

package/dist/core/extract.d.ts

@@ -41,6 +41,8 @@ export interface Observation {
     /** Episode uids it was told in. */
     provenance: string[];
     concepts: string[];
+    /** Questions it answers, in the asker's words (searched beside its text, quieter). */
+    cues: string[];
     origin?: MemoryOrigin;
 }
 export interface KeptEpisode {
@@ -72,6 +74,7 @@ type RawObservation = {
     phase?: string;
     requests?: number[];
     concepts?: unknown;
+    cues?: unknown;
 };
 /** The observations as memory keeps them: with text, from a request of this part, scrubbed; a date only when it is one. */
 export declare function cleanObservations(raw: RawObservation[], uidOf: (n: number) => string | undefined): Observation[];

package/dist/core/extract.js

@@ -42,9 +42,9 @@ what they tell about themselves counts as much. For each:
 - text: 10 to 60 words that stand alone — the event or fact itself, as told ("Melanie took her family camping in the
   mountains"), never "On <date>, X said that …" (the date has its own field). Name who and what (names, never "he",
   "she", "it", "they"); keep every proper noun, title, number and quoted phrase exactly. A time said relatively stays
-  as said, with the date it means, read off the Calendar line of the day it was said: "last week (the week of 19 June
-  2023)", "yesterday (7 May 2023)". When the part names something only by description ("the book you recommended", "my
-  home country", "the kids") and KNOWN FROM OTHER CONVERSATIONS names it, write the name too ("Becoming Nicole",
+  as said, with the date it means, read off the Calendar line of the day it was said: "last week (the week before 26 June
+  2023)", "yesterday (7 May 2023)", "on Friday (12 April 2024)". When the part names something only by description
+  ("the book you recommended", "my home country", "the kids") and KNOWN FROM OTHER CONVERSATIONS names it, write the name too ("Becoming Nicole",
   "Sweden", "her three children") — never a fact from KNOWN that this part does not tell. What the person or a speaker
   says about their own life is true as told: no commentary on what the conversation did or did not confirm. A plan is
   written as a plan ("Melanie planned to go swimming with the kids"). When it replaces something said before, say both
@@ -52,7 +52,8 @@ what they tell about themselves counts as much. For each:
 - about: who or what it is about, named as the conversation names them ("the person" for the one whose requests these
   are, unless the conversation names them).
 - event_date: when it happened or applies, resolved with the Calendar line of the day its request was made ("yesterday"
-  is that line's yesterday; "last week" its last week's first day; "last month" its last month; "in June" is 2023-06)
+  is that line's yesterday; "last week" the first day of its week before; "last weekend" its last weekend's Saturday;
+  "on Friday" the Friday among its days before; "last month" its last month; "in June" is 2023-06)
   — YYYY-MM-DD, YYYY-MM or
   YYYY, as precise as the conversation makes it; empty when no time is given or implied. A plan's event_date is when it
   is planned for.
@@ -63,7 +64,10 @@ what they tell about themselves counts as much. For each:
   implies no such time, and for a one-off event (its event_date says it).
 - phase: done (it happened), plan (intended, not done yet), ongoing, or state (how things are).
 - requests: the request numbers it comes from.
-- concepts: up to 6 specific things it names — people, places, organisations, products, titles, files, services.`;
+- concepts: up to 6 specific things it names — people, places, organisations, products, titles, files, services.
+- cues: 2 to 4 questions someone may ask later that this answers, in the words they would ask in rather than its own —
+  from the broad ("What instruments does Priya play?", "Who are Priya's siblings?") to the specific ("When did Priya
+  start the cello?"), in the language the conversation is in.`;
 const SYSTEM = `You consolidate the long-term memory of a person who works with AI agents (coding, research, writing,
 operations). You get part of one of their conversations: the person's requests (numbered, each with its date), the
 agent's steps (tool calls, with errors) and what the agent said. Ask of everything you write: will a future agent act
@@ -184,12 +188,13 @@ const SCHEMA = {
         observations: {
             type: 'array',
             items: {
-                type: 'object', additionalProperties: false, required: ['text', 'about', 'event_date', 'start_date', 'end_date', 'phase', 'requests', 'concepts'],
+                type: 'object', additionalProperties: false, required: ['text', 'about', 'event_date', 'start_date', 'end_date', 'phase', 'requests', 'concepts', 'cues'],
                 properties: {
                     text: { type: 'string' }, about: { type: 'string' }, event_date: { type: 'string' },
                     start_date: { type: 'string' }, end_date: { type: 'string' },
                     phase: { type: 'string', enum: [...PHASES] },
                     requests: { type: 'array', items: { type: 'integer' } }, concepts: { type: 'array', items: { type: 'string' } },
+                    cues: { type: 'array', items: { type: 'string' } },
                 },
             },
         },
@@ -244,7 +249,7 @@ export function cleanObservations(raw, uidOf) {
             text, about: redactString((x.about ?? '').trim()), eventAt: dateOf(x.event_date),
             ...(dateOf(x.start_date) ? { startAt: dateOf(x.start_date) } : {}), ...(dateOf(x.end_date) ? { endAt: dateOf(x.end_date) } : {}),
             phase: PHASES.includes(String(x.phase)) ? x.phase : 'done',
-            provenance, concepts: cleanConcepts(x.concepts),
+            provenance, concepts: cleanConcepts(x.concepts), cues: cleanCues(x.cues).slice(0, 4),
         });
     }
     return out;

package/dist/core/qdrant-client.js

@@ -46,6 +46,10 @@ const SMALL = { optimizers_config: { default_segment_number: 2 } };
  *  was the best share on both benchmarks, and CombSUM beat rank fusion at the top of both — LoCoMo requests any@3
  *  71.6 → 74.5, nDCG@10 64.6 → 65.7; LongMemEval-S any@1 63.4 → 64.5, sessions any@1 92.6 → 93.2. */
 const DENSE_SHARE = 0.7;
+/** Cues — the questions an item answers, in the asker's words — search as their own channel at this share of the dense
+ *  weight rather than among the item's points. Measured on LoCoMo's 1,307 held-out questions, together with cues on
+ *  every observation and the seven-days-before calendar: multi-hop 50.6 → 55.2, overall 77.2 → 77.4 (docs/RESEARCH.md). */
+const CUE_SHARE = 0.1;
 /** A point's id from its item and its place (0 = the key, n = the n-th child): the same item writes the same ids. */
 export function pointId(item, n) {
     const h = createHash('sha1').update(`${item}#${n}`).digest('hex');
@@ -278,15 +282,19 @@ export class QdrantClient {
         const channels = [];
         const sparse = q.sparse?.indices.length ? q.sparse : null;
         const denseWeight = (sparse ? DENSE_SHARE : 1) / Math.max(1, q.dense.length);
-        for (const v of q.dense)
-            channels.push({ query: v, using: 'dense', params: RESCORE, weight: denseWeight });
+        const cueOff = { ...(filter ?? {}), must_not: [...(filter?.must_not ?? []), { key: 'part', match: { value: 'cue' } }] };
+        const cueOnly = { ...(filter ?? {}), must: [...(filter?.must ?? []), { key: 'part', match: { value: 'cue' } }] };
+        for (const v of q.dense) {
+            channels.push({ query: v, using: 'dense', params: RESCORE, weight: denseWeight * (1 - CUE_SHARE), filter: cueOff });
+            channels.push({ query: v, using: 'dense', params: RESCORE, weight: denseWeight * CUE_SHARE, filter: cueOnly });
+        }
         if (sparse)
             channels.push({ query: sparse, using: 'bm25', weight: 1 - DENSE_SHARE });
         if (!channels.length)
             return [];
         const lists = await Promise.all(channels.map((c) => this.call('POST', `/collections/${this.collection}/points/query/groups`, {
             query: c.query, using: c.using, ...(c.params ? { params: c.params } : {}),
-            ...(filter ? { filter } : {}),
+            ...(c.filter ?? filter ? { filter: c.filter ?? filter } : {}),
             group_by: 'item',
             group_size: 1,
             limit: per,

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 }),
+        gather: (s) => memoryGather(deps, s, { ask, ...(s.limit ? { limit: s.limit } : {}) }),
         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.1.0",
+  "version": "0.2.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",