@cerebriline/core 4.100.264 → 4.100.265

package/dist/services/retrieval/memory-recall.d.ts

@@ -24,14 +24,18 @@
  * however poor: by keyword, "the" and "project" match every note. Asked for
  * by the model that is fine, it asked. Attached unasked to every message it
  * is noise, so a note is attached only when something says it is about the
- * message: the reranker passed it, or it is close by meaning, or it shares
- * two meaningful words with what was searched for.
+ * message: the reranker scored it high, or it is close by meaning, or it
+ * shares two meaningful words with what was searched for.
  *
  * Nothing here can fail a turn. A search that throws, an expander that times
  * out, a server that is down: the message goes to the model without notes.
+ * But the user is told, in other words than "nothing found": a recall that
+ * cannot run and a Memory with nothing to say end the same way for the
+ * model, and are two different things to put right.
  */
 import { type MemoryToolsConfig } from "../../extensions/tools/memory-tools";
 import { type Memory, type RecalledMemory } from "./memory";
+import { type DescribedPlaceCheck } from "./memory-note";
 /** A message shorter than this is "yes", "continue", "go on": nothing to search for. */
 export declare const MEMORY_RECALL_MIN_PROMPT_CHARS = 12;
 /** A pasted log is not a question. Both ends are kept: the ask is at one of them. */
@@ -48,6 +52,25 @@ export declare const HYDE_TIMEOUT_MS = 20000;
 export declare const AUTO_RECALL_MIN_SIMILARITY = 0.5;
 /** Meaningful words a note has to share with the search to be attached unasked. */
 export declare const AUTO_RECALL_MIN_SHARED_WORDS = 2;
+/**
+ * The reranker's score that passes a note on its own. Its own floor, apart
+ * from the user's threshold, which defaults to 0 and would pass every note.
+ * Below it the note still has the other two tests.
+ */
+export declare const AUTO_RECALL_MIN_RELEVANCE = 0.5;
+/**
+ * The share of the session's window the notes may take. A share and not a
+ * count: five notes of 4000 characters are a fifth of a 32k window.
+ */
+export declare const MEMORY_RECALL_WINDOW_SHARE = 0.04;
+/** The window assumed when the host does not say: the smallest in common use. */
+export declare const MEMORY_RECALL_FALLBACK_WINDOW = 32768;
+/**
+ * Notes added for the files a task has in play, after the message's own and
+ * never in their place (claude-hooks cd71cf3 adds up to 12 for a council's
+ * judges; a chat turn has a smaller window to share).
+ */
+export declare const MEMORY_RECALL_PLACE_EXTRA = 3;
 export declare const HYDE_SYSTEM_PROMPT = "You are a memory recall assistant. You are given a user's message and a few related notes retrieved from a knowledge base. Using ONLY facts consistent with those notes, write the short note that would answer the message, as if it were itself a stored note. Prefer the terms and specifics of the notes given. Do not invent facts beyond them. Two or three sentences. State facts; do not explain, and do not address the user.";
 export declare function buildHydeUserPrompt(question: string, notes: string[]): string;
 /** Writes the hypothetical note. Undefined or empty: search without it. */
@@ -63,6 +86,20 @@ export interface MemoryRecallInput {
     cwd: string;
     /** Notes already given to a session are not given to it again. */
     sessionId?: string;
+    /**
+     * The notes still in the conversation, by id (`recalledMemoryIds` reads
+     * them from its messages). Given, they are what counts as given: a note
+     * a compaction folded away can be given again. Left out, a note is given
+     * once per session.
+     */
+    inConversation?: readonly string[];
+    /** The session's window, in tokens, which bounds how much is attached. */
+    contextWindow?: number;
+    /**
+     * The files this task has in play: read, edited, mentioned. Notes about
+     * them are added after the message's own.
+     */
+    places?: readonly string[];
 }
 export interface MemoryRecallResult {
     /** The block to put after the user's message. Absent: nothing found. */
@@ -71,8 +108,10 @@ export interface MemoryRecallResult {
     ids: string[];
     /** Whether the expander's note was searched with. */
     expanded: boolean;
-    /** One line for the user: what was recalled. */
+    /** One line for the user: what was recalled, or why nothing could be. */
     summary?: string;
+    /** Why the recall did not run. Not the same as nothing being found. */
+    failed?: string;
 }
 export type MemoryRecaller = (input: MemoryRecallInput) => Promise<MemoryRecallResult | undefined>;
 export interface CreateMemoryRecallerOptions {
@@ -93,5 +132,26 @@ export declare function isAboutTheSearch(search: string, item: RecalledMemory):
 export declare function clampRecallQuery(query: string, maxChars?: number): string;
 /** Reciprocal-rank fusion of two orderings of notes, best first. */
 export declare function fuseRecalls(first: RecalledMemory[], second: RecalledMemory[], limit: number): RecalledMemory[];
-export declare function formatRecalledMemory(items: RecalledMemory[]): string;
+/** A recalled note, and why it was given when it was not for the message's words. */
+export type GivenNote = RecalledMemory & {
+    via?: string;
+};
+/** How many characters of notes a window of this size takes. */
+export declare function recallCharBudget(contextWindow: number | undefined): number;
+/**
+ * The notes that fit in this many characters, best first. A note that does
+ * not fit is left for the next, smaller ones; the best note is always given,
+ * cut if it has to be, with the id to recall it whole.
+ */
+export declare function fitRecalledMemory(items: GivenNote[], maxChars: number): {
+    items: GivenNote[];
+    cut?: string;
+};
+export declare function formatRecalledMemory(items: GivenNote[], checksFor?: (item: GivenNote) => readonly DescribedPlaceCheck[] | undefined): string;
+/**
+ * The ids of the notes recall attached that are still in these texts: the
+ * head line of each, as `formatRecalledMemory` writes it. A compaction that
+ * kept a note word for word kept that line with it.
+ */
+export declare function recalledMemoryIds(texts: Iterable<string>): string[];
 export declare function createMemoryRecaller(options: CreateMemoryRecallerOptions): MemoryRecaller;

package/dist/services/retrieval/memory.d.ts

@@ -17,7 +17,8 @@
 import { type MemorySettings } from "@cerebriline/shared";
 import type { RetrievalEndpoint } from "./embedding-client";
 import { type EmbedPendingResult, type LibraryOptions, type LibraryVectorSet } from "./library";
-export interface MemoryItem {
+import { type MemoryKind, type MemoryNoteFields, type MemoryOrigin, type MemoryPlace, type MemoryStatus } from "./memory-note";
+export interface MemoryItem extends Partial<MemoryNoteFields> {
     /** `m12`: what `forget` takes. */
     id: string;
     text: string;
@@ -26,6 +27,26 @@ export interface MemoryItem {
     tags: string[];
     createdAt: string;
 }
+/** What `remember` did with a note. */
+export type RememberOutcome = 
+/** Kept as a new note. */
+"added"
+/** Already there; new tags, places or evidence were added to it. */
+ | "updated"
+/** Already there, word for word, with nothing new. */
+ | "unchanged"
+/** The note it replaces now says this, under the same id. */
+ | "revised"
+/** Not kept: a note there says nearly the same. */
+ | "similar";
+/**
+ * Two notes this alike say the same thing (claude-hooks dedup.py: 0.85 of
+ * the first 500 characters, there by SequenceMatcher, here by the letter
+ * pairs both share).
+ */
+export declare const NEAR_DUPLICATE_SIMILARITY = 0.85;
+/** How alike two notes read, 0 to 1: the share of letter pairs they have in common. */
+export declare function noteSimilarity(a: string, b: string): number;
 export interface RecalledMemory extends MemoryItem {
     /** The reranker's score, 0 to 1, when there was one. */
     relevance?: number;
@@ -57,7 +78,7 @@ export interface MemoryExport {
         text: string;
         tags: string[];
         createdAt: string;
-    }>;
+    } & Partial<Pick<MemoryNoteFields, "kind" | "status" | "reason" | "places" | "evidence" | "history" | "settled" | "origin" | "revisedAt">>>;
 }
 export declare const MEMORY_EXPORT_FORMAT = "cerebriline-memory";
 /** A memory is a note, not a document: longer than this belongs in the Library. */
@@ -66,6 +87,41 @@ export declare const MEMORY_NAME_MAX_CHARS = 60;
 export declare function resolveMemoryDirectory(): string;
 /** A name as it is kept: trimmed, one line, of a length a list can show. */
 export declare function normalizeMemoryName(name: string): string;
+/**
+ * The key a note is kept under: its text with spacing and case evened out,
+ * hashed. "Run the tests with vitest" noted twice, once with a capital and a
+ * trailing newline, is one note. The key is the source of the note's
+ * document, so it never changes with the chunk settings and neither does
+ * the note's id.
+ */
+export declare function memoryNoteKey(text: string): string;
+/** What became of a place a note gives. */
+export interface PlaceCheck {
+    place: MemoryPlace;
+    /**
+     * `ok`: there as noted. `moved`: its line is now at `line`. `changed`:
+     * the line is no longer in the file. `missing`: no such file.
+     * `ambiguous`: more than one file it could be.
+     */
+    state: "ok" | "moved" | "changed" | "missing" | "ambiguous";
+    line?: number;
+}
+/** The workspace's files, relative, bounded and kept a minute. */
+export declare function workspaceFiles(cwd: string): string[];
+/**
+ * The rubric a model distils expired notes by (claude-hooks M14): keep what
+ * was found and decided and what is still open; drop the process -- the
+ * attempts, the retries, the order things were tried in.
+ */
+export declare const MEMORY_DISTILL_SYSTEM_PROMPT = "You distil a project's expired notes into one. Keep every finding that still says something about the project, every decision with its reason, and every open question. Drop the process: attempts, retries, dead ends that taught nothing, the order things were tried in. Keep names, paths, commands and numbers exactly as written. Write plain sentences, at most 12 of them, with nothing before or after the note.";
+export declare function buildMemoryDistillPrompt(notes: readonly MemoryItem[]): string;
+/** Whether two paths name one file: the same, or one a path suffix of the other. */
+export declare function sameFile(a: string, b: string): boolean;
+/**
+ * 1 when two lists of places share one (the same file, lines close or not
+ * given), 0.5 when they share only a file, else 0.
+ */
+export declare function placeScore(a: readonly MemoryPlace[], b: readonly MemoryPlace[]): number;
 export declare class Memory {
     private readonly library;
     private readonly directory;
@@ -81,6 +137,13 @@ export declare class Memory {
      * memory named after the folder, made for that workspace.
      */
     private migrate;
+    /**
+     * Bring notes kept under the first key (the exact text) to the key they
+     * have now. Notes that turn out the same are one: the oldest stays, with
+     * the tags of all of them, so its id is the one that keeps working.
+     */
+    private rekeyNotes;
+    private textOf;
     private freeName;
     /** Every memory in the store, the main one first. */
     listMemories(): MemoryInfo[];
@@ -99,21 +162,86 @@ export declare class Memory {
     /** The collections of these memories; a name that is not a memory is left out. */
     private collections;
     private toItem;
-    /** Keep a note. The same text in the same memory is kept once. */
+    /**
+     * The document a note id names, in the memories in reach: the note itself,
+     * or the one it was merged into.
+     */
+    private resolveNote;
+    /** One note by id, from the memories named; one merged away reads as the note it went into. */
+    get(id: string, options?: {
+        memories?: readonly string[];
+    }): MemoryItem | undefined;
+    /**
+     * The places a note gives, with the line each read when it was kept, so a
+     * recall can tell later whether the code moved under it.
+     */
+    private placesFrom;
+    /**
+     * Keep a note. The same text in the same memory is kept once, whatever
+     * its spacing and case; noted again, it gains the new tags, places and
+     * evidence. A note that says nearly what one there says is not kept: the
+     * answer names that one, to be revised (`replaces`) rather than doubled.
+     */
     remember(input: {
         text: string;
         /** @default the main memory */
         memory?: string;
         tags?: readonly string[];
+        /** @default "fact" */
+        kind?: MemoryKind;
+        /** Why: required for a decision. */
+        reason?: string;
+        /** `path` or `path:line`, the places in the code the note is about. */
+        places?: readonly string[];
+        /** What showed it, appended to what the note already has. */
+        evidence?: string;
+        /** A note id: that note now says this, under its own id. */
+        replaces?: string;
+        /** Who keeps it, and in which task. */
+        origin?: MemoryOrigin;
+        /** Where the places' paths are read from. */
+        cwd?: string;
+        /** Keep it even when a note says nearly the same. For imports. */
+        allowSimilar?: boolean;
+        /** Days until it expires; 0 or left out, never. */
+        ttlDays?: number;
         /** For an imported note: when it was first noted. */
         createdAt?: string;
         endpoints?: MemoryEndpoints;
         signal?: AbortSignal;
     }): Promise<{
         item: MemoryItem;
-        outcome: "added" | "unchanged";
+        outcome: RememberOutcome;
+        /** For "similar": how alike, 0 to 1. */
+        similarity?: number;
         note?: string;
     }>;
+    /** Embedded now, so the next recall finds it by meaning. A failure loses nothing: it is embedded with the next note. */
+    private embedNew;
+    /**
+     * The note in this memory that says nearly the same, if one does: found
+     * by the same search a recall makes, by meaning when there are vectors,
+     * and judged on the text.
+     */
+    private nearest;
+    /** Give a note new text, keeping its id; what it said before is kept with it. */
+    private revise;
+    /**
+     * The user's verdict on a note: confirmed or outdated, each with why, or
+     * back to noted. Only the user's: no tool the model has calls this.
+     *
+     * A verdict without a reason is refused, as claude-hooks' findings ledger
+     * refuses one: the reason is what the reading model weighs a later
+     * contradiction against, and "confirmed" alone gives it nothing to weigh.
+     */
+    settle(id: string, verdict: {
+        status: MemoryStatus;
+        reason?: string;
+    }, options?: {
+        memories?: readonly string[];
+    }): MemoryItem;
+    /** Count a use of these notes: they were given to a task. */
+    noteRecalled(ids: readonly string[], memories: readonly string[]): void;
     /** The notes that best match, best first, from the memories named. */
     recall(query: string, options?: {
         /** @default the main memory */
@@ -122,10 +250,25 @@ export declare class Memory {
         endpoints?: MemoryEndpoints;
         limit?: number;
         signal?: AbortSignal;
+        /** Leave out the notes the user marked outdated. */
+        skipOutdated?: boolean;
     }): Promise<{
         items: RecalledMemory[];
         notes: string[];
     }>;
+    /**
+     * Notes about the files in play: those whose places, or whose text, name
+     * a file among `paths`, best place first. For a recall keyed on the
+     * prompt, which misses the notes about the code a task has open (claude-
+     * hooks cd71cf3: over 8 councils this pass added 5-9 findings each,
+     * settled ones the question alone never reached). A shared file counts;
+     * shared words alone never do.
+     */
+    recallAtPlaces(paths: readonly string[], options?: {
+        memories?: readonly string[];
+        limit?: number;
+        exclude?: readonly string[];
+    }): RecalledMemory[];
     /** Every note of the memories named, newest first. */
     list(options?: {
         memories?: readonly string[];
@@ -134,6 +277,45 @@ export declare class Memory {
     forget(id: string, options?: {
         memories?: readonly string[];
     }): Promise<boolean>;
+    /**
+     * Merge the notes of a memory that say nearly the same. The oldest of
+     * each set stays, with every tag, place and piece of evidence, and the
+     * ids of the others, so a reference to one still reaches it; the others
+     * are deleted. A consolidation that only reported merges and left the
+     * notes in place grew the store while it said it shrank it (claude-hooks
+     * v1.15). A note the user confirmed is never merged into one they did not.
+     */
+    consolidate(options?: {
+        memories?: readonly string[];
+    }): Promise<{
+        merged: number;
+        into: string[];
+    }>;
+    /**
+     * Hold a note's places against the code as it is now. A short path is
+     * found by the one file it is a suffix of (as the council's citation
+     * check does); two such files is ambiguous, not missing. A line kept
+     * with its text is looked for where it was, then anywhere in the file.
+     */
+    checkPlaces(item: Pick<MemoryItem, "places">, cwd: string, files?: () => readonly string[]): PlaceCheck[];
+    /**
+     * Distil the notes that have expired into one, then remove them: the
+     * notes of a fact that were only ever noted, past the day they were kept
+     * until. One summary per memory, kept with no expiry; the originals go
+     * only once it is written (claude-hooks M14). With no `distill`, or a
+     * distillation that fails, they stay where they are.
+     */
+    expire(options: {
+        distill: (notes: readonly MemoryItem[]) => Promise<string | undefined>;
+        nowMs?: number;
+        memories?: readonly string[];
+        endpoints?: MemoryEndpoints;
+    }): Promise<Array<{
+        memory: string;
+        distilled?: string;
+        removed: number;
+        kept?: string;
+    }>>;
     /** A memory as a file's content. The notes only: vectors are made again where it is read. */
     exportMemory(name: string): MemoryExport;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@cerebriline/core",
 	"description": "Cerebriline Core SDK for Node Runtime",
-	"version": "4.100.264",
+	"version": "4.100.265",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mann1x/cline.git",
@@ -80,9 +80,9 @@
 		"ws": "^8.20.0",
 		"yaml": "^2.8.2",
 		"zod": "4.4.3",
-		"@cerebriline/agents": "4.100.264",
-		"@cerebriline/llms": "4.100.264",
-		"@cerebriline/shared": "4.100.264"
+		"@cerebriline/agents": "4.100.265",
+		"@cerebriline/llms": "4.100.265",
+		"@cerebriline/shared": "4.100.265"
 	},
 	"peerDependencies": {
 		"posthog-node": "^5.8.0"