Skip to slide
066 / 221

CH 05 · Context Engineering and Memory · 06/18

Read as one page

Real code: OpenClaw's memory search returns addresses, not files

OpenClaw is a personal-assistant agent built on pi's agent core. Files under memory/ are not in the default bootstrap list, so they stay on disk until a tool reads them. For a private session, MEMORY.md and USER.md are also copied into the system prompt, up to 20,000 and 4,000 characters by default. memory_search returns a path and a line range, and memory_get reads that slice.

export type MemorySearchResult = {
  path: string;          // [1]
  startLine: number;
  endLine: number;
  score: number;
  vectorScore?: number;
  textScore?: number;
  snippet: string;       // [2]
  source: MemorySource;
  // ... (6 lines: optional rank and project metadata)
  citation?: string;
  provenance?: MemoryEntryProvenance;
};

Source: openclaw/openclaw, packages/memory-host-sdk/src/host/types.ts (MIT)

export function buildMemoryReadResult(params: {
  content: string;
  relPath: string;
  from?: number;
  lines?: number;
  defaultLines?: number;
  maxChars?: number;
  suggestReadFallback?: boolean;
}): MemoryReadResult {
  const fileLines = params.content.split("\n");
  // ... (5 lines: drop the empty entry a trailing newline leaves behind)
  const start = resolveIntegerOption(params.from, 1, { min: 1 });   // [3]
  const requestedCount = resolveIntegerOption(
    params.lines ?? params.defaultLines,
    DEFAULT_MEMORY_READ_LINES,                                      // [4]
    { min: 1 },
  );
  const selectedLines = fileLines.slice(start - 1, start - 1 + requestedCount);
  const moreSourceLinesRemain = start - 1 + selectedLines.length < fileLines.length; // [5]

Source: openclaw/openclaw, packages/memory-host-sdk/src/host/read-file-shared.ts (MIT)

What to notice

  1. [1] Every hit carries path, startLine, and endLine. When citations are included, the snippet gains Source: plus #L<start> for one line, or #L<start>-L<end> for a range. The default mode is auto: ordinary sessions get that line, and a session key with a group or channel segment does not.
  2. [2] snippet is a short preview. vectorScore is the meaning match, textScore is the keyword match, and score is the sort key. If the embedding lookup fails and keyword search is available, the tool returns those keyword hits only. source is memory or sessions. provenance, when set, is the origin: owner, agent, untrusted, or system.
  3. [3] memory_get takes the path back, with an optional from line and lines count. resolveIntegerOption turns a missing from, or one below 1, into line 1.
  4. [4] When lines is omitted, the reader takes up to 120 lines (DEFAULT_MEMORY_READ_LINES), then keeps only what fits in 12,000 characters. The continuation note is added after that cut.
  5. [5] moreSourceLinesRemain means the file goes on past the slice. If more lines remain and the slice itself fit the character budget, the reply ends with [More content available. Use from=N to continue.]

When both tools are on, the prompt says to search, then to memory_get the needed lines, and not to search again when the supplied context already answers. A file under memory/ costs nothing until a search reads it, and then only the lines memory_get returns. MEMORY.md is injected on every private turn, up to the bootstrap cap.

Read it yourself: open extensions/memory-core/src/memory-tool-contract.ts and read buildMemoryPromptSection. When memory_search is off and memory_get is on, the prompt sends the model straight to a known file. Then read buildMemoryReadResultFromSlice in read-file-shared.ts and see what is said when one line is longer than the character budget.

Finished this idea?

Your learning progress stays in this browser.