typeclaw 0.36.8 → 0.37.1

package/src/bundled-plugins/memory/search-tool.ts

@@ -1,15 +1,20 @@
+import { writeFile } from 'node:fs/promises'
+
 import { z } from 'zod'
 
 import { defineTool } from '@/plugin'
 
-import { loadAllShards, type TopicShard } from './load-shards'
+import { loadAllShards, loadShard, type TopicShard } from './load-shards'
+import { renderReference } from './references/frontmatter'
+import { loadAllReferences, loadReference, type Reference } from './references/load-references'
 import type { FragmentEvent, LegacyProseEvent, StreamEvent } from './stream-events'
 import { readAllUndreamedStreamDays, type UndreamedStreamDay } from './stream-io'
 
 const DEFAULT_MAX_RESULTS = 10
 const EXCERPT_CONTEXT_LINES = 3
+const EXCERPT_HEAD_LINES = 7
 
-type TopicMatch = {
+export type TopicMatch = {
   source: 'topic'
   shardPath: string
   slug: string
@@ -18,7 +23,7 @@ type TopicMatch = {
   fullBody?: string
 }
 
-type StreamMatch = {
+export type StreamMatch = {
   source: 'stream'
   streamPath: string
   date: string
@@ -28,43 +33,135 @@ type StreamMatch = {
   fullBody?: string
 }
 
-type MemorySearchMatch = TopicMatch | StreamMatch
+export type ReferenceMatch = {
+  source: 'reference'
+  slug: string
+  title: string
+  excerpt: string
+  created: string
+  fullBody?: string
+}
 
-type MemorySearchResult = { matches: MemorySearchMatch[]; truncatedAt?: number } | { error: string }
+export type MemorySearchMatch = TopicMatch | StreamMatch | ReferenceMatch
+
+export type MemorySearchResult = { matches: MemorySearchMatch[]; truncatedAt?: number } | { error: string }
+
+export type Matcher = (haystack: string) => boolean
+
+export function createMemorySearchTool() {
+  return defineTool({
+    description:
+      'Search the agent\'s long-term memory, or look up one topic shard by exact slug. Covers topic shards under memory/topics/ (consolidated facts), references under memory/references/ (verbatim artifacts), and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Pass `query` for search OR `topic` for an exact slug lookup, not both. Search is case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). `topic` skips search entirely and returns that one shard (or reference) with its full body — use it to read a topic OR reference whose slug you already have (e.g. a heading shown in injected memory); it resolves the topic shard first and falls back to a reference of the same slug. Returns matches discriminated by `source: "topic" | "reference" | "stream"`, each with line-context excerpts; full=true includes complete bodies (topic lookups always include the full body). Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then reference matches, then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-then-reference-then-stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match.',
+    parameters: z.object({
+      query: z.string().optional(),
+      topic: z.string().optional(),
+      asRegex: z.boolean().default(false),
+      full: z.boolean().default(false),
+      maxResults: z.number().int().min(0).default(DEFAULT_MAX_RESULTS),
+      since: z.string().optional(),
+      before: z.string().optional(),
+    }),
+    async execute({ query, topic, asRegex, full, maxResults, since, before }, ctx) {
+      if ((query === undefined) === (topic === undefined)) {
+        return resultToToolResult({ error: 'provide exactly one of `query` or `topic`' })
+      }
+
+      if (topic !== undefined) {
+        return resultToToolResult(await lookupTopic(ctx.agentDir, topic, ctx.logger))
+      }
+
+      const matcherOrError = buildMatcher(query!, asRegex)
+      if (typeof matcherOrError === 'string') {
+        return resultToToolResult({ error: matcherOrError })
+      }
+
+      const [shards, streamDays, allReferences] = await Promise.all([
+        loadAllShards(ctx.agentDir, { logger: ctx.logger }),
+        readAllUndreamedStreamDays(ctx.agentDir),
+        loadAllReferences(ctx.agentDir, { logger: ctx.logger }),
+      ])
+      const dateFilter = parseReferenceDateFilter(since, before)
+      if ('error' in dateFilter) return resultToToolResult(dateFilter)
+
+      const references = allReferences.filter((reference) => referenceCandidateAllowed(reference, dateFilter))
+      if (shards.length === 0 && streamDays.length === 0 && references.length === 0) {
+        return resultToToolResult({ matches: [], truncatedAt: 0 })
+      }
+
+      let result = searchAll(shards, streamDays, matcherOrError, { full, maxResults, references })
+      if ('matches' in result && result.matches.length === 0) {
+        const fallback = tokenFallback(query!, asRegex, shards, streamDays, references, { full, maxResults })
+        if (fallback !== null) result = fallback
+      }
+      if ('matches' in result) await bumpReturnedReferences(allReferences, result.matches)
+      return resultToToolResult(result)
+    },
+  })
+}
 
-type Matcher = (haystack: string) => boolean
+export const memorySearchTool = createMemorySearchTool()
+
+// Exact slug lookup, so the agent can read a topic OR reference whose slug the
+// per-turn injection already showed it without re-running a fuzzy search for a
+// body the retrieval layer already located. The injected memory block renders
+// both topic and reference entries with a `slug:` line and a single recovery
+// hint (`memory_search({ topic: "<slug>" })`), so this lookup must resolve both:
+// it tries the topic shard first, then falls back to a reference of the same
+// slug. A traversal slug makes the path builder throw inside the loader — caught
+// and returned as a structured error, not a crash. A slug that matches neither
+// returns empty matches, the same shape as a search that hit nothing.
+async function lookupTopic(
+  agentDir: string,
+  slug: string,
+  logger?: { warn(message: string): void },
+): Promise<MemorySearchResult> {
+  const loaderOptions = logger === undefined ? {} : { logger }
+  let shard: TopicShard | null
+  try {
+    shard = await loadShard(agentDir, slug, loaderOptions)
+  } catch (err) {
+    return { error: `invalid topic slug: ${err instanceof Error ? err.message : String(err)}` }
+  }
+  if (shard !== null) return { matches: [topicMatchWithFullBody(shard)] }
+
+  const reference = await loadReference(agentDir, slug, loaderOptions)
+  if (reference !== null) {
+    const match = referenceMatchWithFullBody(reference)
+    // A reference reached via topic-slug lookup is a real access — record it so
+    // it advances accessCount/lastAccessed the same as a query hit, otherwise the
+    // injected-slug use case this fallback unlocks would still decay as unused.
+    await bumpReturnedReferences([reference], [match])
+    return { matches: [match] }
+  }
 
-export const memorySearchTool = defineTool({
-  description:
-    'Search the agent\'s long-term memory. Covers both topic shards under memory/topics/ (consolidated facts) and undreamed daily-stream events under memory/streams/ (recent fragments not yet folded into shards). Case-insensitive substring by default: tries the whole query as one phrase first, and if that finds nothing, falls back to OR-matching the individual words (ranked by how many words each hit contains) — so a multi-word query still returns results even when no entry contains the exact phrase. asRegex=true treats query as a JavaScript regex (no word fallback). Returns matches discriminated by `source: "topic" | "stream"`, each with line-context excerpts; full=true includes complete bodies. Ordering depends on mode: exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then stream matches (newest day first); word-fallback results are ranked by matched-word count, with that same topic-first/stream-newest order as the tiebreak within each score band, so a higher-scoring stream match can precede a lower-scoring topic match.',
-  parameters: z.object({
-    query: z.string(),
-    asRegex: z.boolean().default(false),
-    full: z.boolean().default(false),
-    maxResults: z.number().int().min(0).default(DEFAULT_MAX_RESULTS),
-  }),
-  async execute({ query, asRegex, full, maxResults }, ctx) {
-    const matcherOrError = buildMatcher(query, asRegex)
-    if (typeof matcherOrError === 'string') {
-      return resultToToolResult({ error: matcherOrError })
-    }
+  return { matches: [] }
+}
 
-    const [shards, streamDays] = await Promise.all([
-      loadAllShards(ctx.agentDir, { logger: ctx.logger }),
-      readAllUndreamedStreamDays(ctx.agentDir),
-    ])
-    if (shards.length === 0 && streamDays.length === 0) {
-      return resultToToolResult({ matches: [], truncatedAt: 0 })
-    }
+function topicMatchWithFullBody(shard: TopicShard): TopicMatch {
+  return {
+    source: 'topic',
+    shardPath: shard.path,
+    slug: shard.slug,
+    heading: shard.frontmatter.heading,
+    excerpt: excerpt(shard.body),
+    fullBody: shard.body,
+  }
+}
 
-    const result = searchAll(shards, streamDays, matcherOrError, { full, maxResults })
-    if ('matches' in result && result.matches.length === 0) {
-      const fallback = tokenFallback(query, asRegex, shards, streamDays, { full, maxResults })
-      if (fallback !== null) return resultToToolResult(fallback)
-    }
-    return resultToToolResult(result)
-  },
-})
+function referenceMatchWithFullBody(reference: Reference): ReferenceMatch {
+  return {
+    source: 'reference',
+    slug: reference.slug,
+    title: reference.frontmatter.title,
+    excerpt: excerpt(reference.body),
+    created: reference.frontmatter.created,
+    fullBody: reference.body,
+  }
+}
+
+function excerpt(body: string): string {
+  return splitBodyLines(body).slice(0, EXCERPT_HEAD_LINES).join('\n')
+}
 
 // Phrase-first/token-fallback: the descriptive multi-word queries the
 // retrieval subagent issues rarely appear verbatim in any body, so a
@@ -81,16 +178,17 @@ function tokenFallback(
   asRegex: boolean,
   shards: TopicShard[],
   streamDays: UndreamedStreamDay[],
+  references: Reference[],
   options: { full: boolean; maxResults: number },
 ): MemorySearchResult | null {
   if (asRegex) return null
   const tokens = distinctTokens(query)
   if (tokens.length === 0) return null
   if (tokens.length === 1 && tokens[0] === query.trim().toLowerCase()) return null
-  return searchAllRanked(shards, streamDays, tokens, options)
+  return searchAllRanked(shards, streamDays, tokens, { ...options, references })
 }
 
-function distinctTokens(query: string): string[] {
+export function distinctTokens(query: string): string[] {
   return [
     ...new Set(
       query
@@ -101,7 +199,7 @@ function distinctTokens(query: string): string[] {
   ]
 }
 
-function buildMatcher(query: string, asRegex: boolean): Matcher | string {
+export function buildMatcher(query: string, asRegex: boolean): Matcher | string {
   if (asRegex) {
     try {
       const regex = new RegExp(query, 'i')
@@ -122,11 +220,11 @@ function buildMatcher(query: string, asRegex: boolean): Matcher | string {
 // before topic matches when `maxResults` is exhausted. The agent reading
 // results in this order sees long-term consolidated truth before recent
 // ephemeral fragments, which mirrors the injection-side rendering order.
-function searchAll(
+export function searchAll(
   shards: TopicShard[],
   streamDays: UndreamedStreamDay[],
   matcher: Matcher,
-  options: { full: boolean; maxResults: number },
+  options: { full: boolean; maxResults: number; references?: Reference[] },
 ): MemorySearchResult {
   const matches: MemorySearchMatch[] = []
   let truncatedAt: number | undefined
@@ -146,6 +244,12 @@ function searchAll(
     if (!push(match)) return { matches, truncatedAt: truncatedAt! }
   }
 
+  for (const reference of options.references ?? []) {
+    const match = matchReference(reference, matcher, options.full)
+    if (match === null) continue
+    if (!push(match)) return { matches, truncatedAt: truncatedAt! }
+  }
+
   for (let i = streamDays.length - 1; i >= 0; i--) {
     const day = streamDays[i]!
     for (const event of day.events) {
@@ -165,19 +269,32 @@ function searchAll(
 // natural enumeration order (topics first in loadAllShards order, then stream
 // days newest-first), so the established ordering contract holds within each
 // score band. maxResults truncation is applied last, after ranking.
-function searchAllRanked(
+//
+// `tokenMatchMode` defaults to 'substring' (the tool-path contract: `memory_search`
+// is a deliberate agent query). The hybrid keyword lane opts into 'ascii-boundary'
+// because its query is a whole user prompt, where unanchored substrings let short
+// tokens ('in', 'do', 'ci') match inside unrelated words and over-score verbose
+// shards. Both the match predicate and the score use the SAME per-token matchers,
+// so a shard cannot rank on a hit the matcher wouldn't have counted.
+export function searchAllRanked(
   shards: TopicShard[],
   streamDays: UndreamedStreamDay[],
   tokens: string[],
-  options: { full: boolean; maxResults: number },
+  options: {
+    full: boolean
+    maxResults: number
+    references?: Reference[]
+    tokenMatchMode?: 'substring' | 'ascii-boundary'
+  },
 ): MemorySearchResult {
+  const tokenMatchers = tokens.map((t) => buildTokenMatcher(t, options.tokenMatchMode ?? 'substring'))
   const anyToken: Matcher = (haystack) => {
     const lower = haystack.toLowerCase()
-    return tokens.some((t) => lower.includes(t))
+    return tokenMatchers.some((matches) => matches(lower))
   }
   const scoreOf = (text: string): number => {
     const lower = text.toLowerCase()
-    return tokens.reduce((n, t) => (lower.includes(t) ? n + 1 : n), 0)
+    return tokenMatchers.reduce((n, matches) => (matches(lower) ? n + 1 : n), 0)
   }
 
   const scored: Array<{ match: MemorySearchMatch; score: number; order: number }> = []
@@ -189,6 +306,12 @@ function searchAllRanked(
     scored.push({ match, score: scoreOf(shardSearchText(shard)), order: order++ })
   }
 
+  for (const reference of options.references ?? []) {
+    const match = matchReference(reference, anyToken, options.full)
+    if (match === null) continue
+    scored.push({ match, score: scoreOf(referenceSearchText(reference)), order: order++ })
+  }
+
   for (let i = streamDays.length - 1; i >= 0; i--) {
     const day = streamDays[i]!
     for (const event of day.events) {
@@ -206,6 +329,27 @@ function searchAllRanked(
   return { matches: scored.map((s) => s.match) }
 }
 
+// A per-token predicate over an ALREADY-lowercased haystack. 'substring' is plain
+// `includes`. 'ascii-boundary' anchors ASCII tokens between alnum boundaries
+// (NOT `\b`, which is unreliable for CJK) so 'in'/'do' stop matching inside
+// 'reload'/'docker'; a token containing any non-ASCII char (e.g. '홍길동') has no
+// reliable ASCII boundary and falls back to substring.
+function buildTokenMatcher(token: string, mode: 'substring' | 'ascii-boundary'): (lowerHaystack: string) => boolean {
+  if (mode === 'substring' || hasNonAscii(token)) {
+    return (lower) => lower.includes(token)
+  }
+  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const boundary = new RegExp(`(?:^|[^a-z0-9])${escaped}(?=$|[^a-z0-9])`)
+  return (lower) => boundary.test(lower)
+}
+
+export function hasNonAscii(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) > 0x7f) return true
+  }
+  return false
+}
+
 function shardSearchText(shard: TopicShard): string {
   return [shard.slug, shard.frontmatter.heading, ...(shard.frontmatter.tags ?? []), shard.body].join('\n')
 }
@@ -216,6 +360,10 @@ function eventSearchText(event: StreamEvent): string {
   return ''
 }
 
+function referenceSearchText(reference: Reference): string {
+  return [reference.slug, reference.frontmatter.title, ...reference.frontmatter.tags, reference.body].join('\n')
+}
+
 function matchShard(shard: TopicShard, matcher: Matcher, full: boolean): TopicMatch | null {
   const bodyLines = splitBodyLines(shard.body)
   const firstBodyLineIndex = bodyLines.findIndex((line) => matcher(line))
@@ -239,6 +387,30 @@ function matchShard(shard: TopicShard, matcher: Matcher, full: boolean): TopicMa
   return match
 }
 
+function matchReference(reference: Reference, matcher: Matcher, full: boolean): ReferenceMatch | null {
+  const bodyLines = splitBodyLines(reference.body)
+  const firstBodyLineIndex = bodyLines.findIndex((line) => matcher(line))
+  const matched =
+    matcher(reference.slug) ||
+    matcher(reference.frontmatter.title) ||
+    reference.frontmatter.tags.some((tag) => matcher(tag)) ||
+    firstBodyLineIndex !== -1
+  if (!matched) return null
+
+  const match: ReferenceMatch = {
+    source: 'reference',
+    slug: reference.slug,
+    title: reference.frontmatter.title,
+    excerpt:
+      firstBodyLineIndex === -1
+        ? fallbackReferenceExcerpt(reference, matcher)
+        : excerptForLine(bodyLines, firstBodyLineIndex),
+    created: reference.frontmatter.created,
+  }
+  if (full) match.fullBody = reference.body
+  return match
+}
+
 // Stream-event matcher. `fragment` events expose `topic` + `body` for search;
 // `legacy_prose` exposes `text` (no id, no topic). `watermark` events carry
 // no human content and are skipped — they only mark dreaming progress.
@@ -315,15 +487,80 @@ function fallbackExcerpt(shard: TopicShard, matcher: Matcher): string {
   return matchedTag ?? shard.frontmatter.heading
 }
 
+function fallbackReferenceExcerpt(reference: Reference, matcher: Matcher): string {
+  if (matcher(reference.frontmatter.title)) return reference.frontmatter.title
+  if (matcher(reference.slug)) return reference.slug
+  const matchedTag = reference.frontmatter.tags.find((tag) => matcher(tag))
+  return matchedTag ?? reference.frontmatter.title
+}
+
+type ReferenceDateFilter = { since?: Date; before?: Date }
+
+function parseReferenceDateFilter(
+  since: string | undefined,
+  before: string | undefined,
+): ReferenceDateFilter | { error: string } {
+  const sinceDate = since === undefined ? undefined : parseDateParam('since', since)
+  if (typeof sinceDate === 'string') return { error: sinceDate }
+  const beforeDate = before === undefined ? undefined : parseDateParam('before', before)
+  if (typeof beforeDate === 'string') return { error: beforeDate }
+  return { since: sinceDate, before: beforeDate }
+}
+
+function parseDateParam(name: string, value: string): Date | string {
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return `invalid ${name}: expected ISO 8601 datetime string`
+  return date
+}
+
+function referenceCandidateAllowed(reference: Reference, filter: ReferenceDateFilter): boolean {
+  if (reference.frontmatter.demoted) return false
+  const created = new Date(reference.frontmatter.created)
+  if (filter.since !== undefined && created < filter.since) return false
+  if (filter.before !== undefined && created >= filter.before) return false
+  return true
+}
+
+async function bumpReturnedReferences(references: Reference[], matches: MemorySearchMatch[]): Promise<void> {
+  const returnedSlugs = new Set(matches.filter((match) => match.source === 'reference').map((match) => match.slug))
+  if (returnedSlugs.size === 0) return
+  await Promise.all(
+    references
+      .filter((reference) => returnedSlugs.has(reference.slug))
+      .map((reference) =>
+        writeFile(
+          reference.path,
+          renderReference(
+            {
+              ...reference.frontmatter,
+              lastAccessed: new Date().toISOString(),
+              accessCount: reference.frontmatter.accessCount + 1,
+            },
+            reference.body,
+          ),
+          'utf8',
+        ),
+      ),
+  )
+}
+
 function excerptForLine(lines: string[], matchIndex: number): string {
   const start = Math.max(0, matchIndex - EXCERPT_CONTEXT_LINES)
   const end = Math.min(lines.length, matchIndex + EXCERPT_CONTEXT_LINES + 1)
   return lines.slice(start, end).join('\n')
 }
 
+const EMPTY_RESULT_GUIDANCE =
+  'No matching memory. This is the authoritative result — memory_search already covers topic shards, references, and undreamed stream events. Do not fall back to grep/find/bash or manually reading memory/topics, memory/references, memory/streams, or sessions; accept that no relevant memory exists and proceed.'
+
+// The empty-set note rides in the LLM-facing `text` ONLY. `details` stays the
+// pure struct: `keywordLane` reads `searchAll` directly (never this layer) and
+// the structured tests assert on `details`, so both must see no `note`.
 function resultToToolResult(result: MemorySearchResult) {
+  const isEmpty = 'matches' in result && result.matches.length === 0
+  const text = isEmpty ? JSON.stringify({ ...result, note: EMPTY_RESULT_GUIDANCE }) : JSON.stringify(result)
   return {
-    content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+    content: [{ type: 'text' as const, text }],
     details: result,
   }
 }

package/src/bundled-plugins/memory/stream-events.ts

@@ -39,6 +39,7 @@ export const fragmentEventSchema = z
     entry: z.string(),
     topic: z.string(),
     body: z.string(),
+    references: z.array(z.string()).optional(),
   })
   .passthrough()
 

package/src/bundled-plugins/memory/stream-io.ts

@@ -1,13 +1,18 @@
 import { readFile, appendFile, readdir, stat, writeFile, rename } from 'node:fs/promises'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 
 import { getDreamedIds, loadDreamingState } from './dreaming-state'
 import { streamsDir } from './paths'
-import { parseEventLine, type StreamEvent } from './stream-events'
+import { parseEventLine, type FragmentEvent, type StreamEvent } from './stream-events'
 
 const STREAM_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/
 const STREAM_DATE_FROM_FILENAME = /^(\d{4}-\d{2}-\d{2})\.jsonl$/
 
+export type FragmentsAppendedContext = {
+  path: string
+  date: string | null
+}
+
 // Per-file event cache. `(mtimeMs, ctimeMs, size)` is the invalidation key,
 // mirroring `load-shards.ts`'s shard cache. The three writers in this module
 // — `appendEvents` (memory-logger appends), `writeEventsAtomic` (dreaming
@@ -104,10 +109,30 @@ export function __resetStreamFileCacheForTests(): void {
   streamFileCache.clear()
 }
 
-export async function appendEvents(path: string, events: readonly StreamEvent[]): Promise<void> {
+export async function appendEvents(
+  path: string,
+  events: readonly StreamEvent[],
+  onFragmentsAppended?: (fragments: FragmentEvent[], context: FragmentsAppendedContext) => Promise<void>,
+  onHookError?: (err: unknown) => void,
+): Promise<void> {
   if (events.length === 0) return
   const joined = events.map((e) => `${JSON.stringify(e)}\n`).join('')
   await appendFile(path, joined, 'utf-8')
+  if (onFragmentsAppended === undefined) return
+
+  const fragments = events.filter((event): event is FragmentEvent => event.type === 'fragment')
+  if (fragments.length === 0) return
+
+  const context: FragmentsAppendedContext = { path, date: streamDateFromPath(path) }
+  try {
+    await onFragmentsAppended(fragments, context)
+  } catch (err) {
+    onHookError?.(err)
+  }
+}
+
+function streamDateFromPath(path: string): string | null {
+  return STREAM_DATE_FROM_FILENAME.exec(basename(path))?.[1] ?? null
 }
 
 export async function writeEventsAtomic(path: string, events: readonly StreamEvent[]): Promise<void> {

package/src/bundled-plugins/memory/turn-dedup.ts

@@ -0,0 +1,40 @@
+import type { TopicShard } from './load-shards'
+
+export type InjectedShardState = Map<string, string>
+
+export type DirectShardPartition = {
+  full: TopicShard[]
+  unchanged: TopicShard[]
+}
+
+// Preserves the "nothing the agent always had vanishes on an off-topic turn"
+// guarantee by AVAILABILITY, not literal presence: an unchanged shard is still
+// named (heading + slug) and its body is recoverable via memory_search, while a
+// changed shard always re-injects in full so the agent never reads a stale body.
+// `state` is the session-scoped record the caller owns and clears on session.end.
+export function partitionDirectShards(shards: TopicShard[], state: InjectedShardState): DirectShardPartition {
+  const full: TopicShard[] = []
+  const unchanged: TopicShard[] = []
+  for (const shard of shards) {
+    const hash = hashBody(shard.body)
+    if (state.get(shard.slug) === hash) {
+      unchanged.push(shard)
+    } else {
+      full.push(shard)
+      state.set(shard.slug, hash)
+    }
+  }
+  return { full, unchanged }
+}
+
+// FNV-1a over the body. A hash collision only suppresses a body the agent can
+// still re-fetch by slug, so collision-tolerance buys a cheap one-string-per-slug
+// state map instead of retaining full bodies per session.
+function hashBody(body: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < body.length; i++) {
+    hash ^= body.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16)
+}

package/src/bundled-plugins/memory/vector/cache-write.ts

@@ -0,0 +1,19 @@
+import { mkdir, writeFile, rename } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Atomically write retrieval cache to memory/.retrieval-cache/<sessionId>.md
+ * using tmp+rename pattern for crash safety.
+ */
+export async function writeRetrievalCache(agentDir: string, sessionId: string, content: string): Promise<void> {
+  const cacheDir = join(agentDir, 'memory', '.retrieval-cache')
+  const cachePath = join(cacheDir, `${sessionId}.md`)
+  const tmpPath = `${cachePath}.tmp`
+
+  // Create directory if it doesn't exist
+  await mkdir(cacheDir, { recursive: true })
+
+  // Write to tmp file, then atomically rename
+  await writeFile(tmpPath, content, 'utf8')
+  await rename(tmpPath, cachePath)
+}

package/src/bundled-plugins/memory/vector/config.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+import { loadPluginConfigsSync } from '@/config'
+
+export const vectorConfigSchema = z
+  .object({
+    enabled: z.boolean().default(false),
+  })
+  .default({ enabled: false })
+
+export type VectorConfig = z.infer<typeof vectorConfigSchema>
+
+// Fails closed to `false`: a memory block we can't parse is treated as opted
+// out. Shared by the host-side download gate and the runtime's per-turn vs
+// system-prompt memory-injection decision, so both read the flag identically.
+export function vectorEnabledFromMemoryConfig(memory: unknown): boolean {
+  if (typeof memory !== 'object' || memory === null) return false
+  const parsed = vectorConfigSchema.safeParse((memory as Record<string, unknown>).vector)
+  return parsed.success && parsed.data.enabled
+}
+
+export function agentUsesVector(cwd: string): boolean {
+  try {
+    return vectorEnabledFromMemoryConfig(loadPluginConfigsSync(cwd).memory)
+  } catch {
+    return false
+  }
+}