opencode-claude-memory 0.1.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kuitos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,71 @@
-# opencode-memory
+<div align="center">
 
-Cross-session memory plugin for [OpenCode](https://opencode.ai) — **fully compatible with Claude Code's memory format**.
+# 🧠 opencode-claude-memory
 
-Claude Code writes memories → OpenCode reads them.  
-OpenCode writes memories → Claude Code reads them.
+**A 1:1 replica of [Claude Code's memory system](https://github.com/anthropics/claude-code) for OpenCode**
 
-## Features
+*Ported from the original source — same paths, same format, same tools, same prompts. Zero drift.*
 
-- **5 tools**: `memory_save`, `memory_delete`, `memory_list`, `memory_search`, `memory_read`
-- **Claude Code compatible**: shares the same `~/.claude/projects/<project>/memory/` directory
-- **Auto-extraction**: shell wrapper that automatically extracts memories after each session
-- **System prompt injection**: existing memories are injected into every conversation
-- **4 memory types**: `user`, `feedback`, `project`, `reference` (same taxonomy as Claude Code)
+Claude Code writes memories → OpenCode reads them. OpenCode writes memories → Claude Code reads them.
 
-## Quick Start
+[![npm version](https://img.shields.io/npm/v/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)
+[![License](https://img.shields.io/npm/l/opencode-claude-memory.svg?style=flat-square)](https://github.com/kuitos/opencode-claude-memory/blob/main/LICENSE)
+
+[Features](#-features) • [Quick Start](#-quick-start) • [How It Works](#-how-it-works) • [Configuration](#%EF%B8%8F-configuration) • [Tools Reference](#-tools-reference)
+
+</div>
+
+---
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🔄 Claude Code Compatible
+Shares the exact same `~/.claude/projects/<project>/memory/` directory — bidirectional sync out of the box
+
+</td>
+<td width="50%">
+
+### 🛠️ 5 Memory Tools
+`memory_save`, `memory_delete`, `memory_list`, `memory_search`, `memory_read`
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### ⚡ Auto-Extraction
+Drop-in `opencode` wrapper that extracts memories in the background after each session
+
+</td>
+<td width="50%">
+
+### 💉 System Prompt Injection
+Existing memories are automatically injected into every conversation
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 📁 4 Memory Types
+`user`, `feedback`, `project`, `reference` — same taxonomy as Claude Code
+
+</td>
+<td width="50%">
+
+### 🌳 Git Worktree Aware
+Worktrees of the same repo share the same memory directory
+
+</td>
+</tr>
+</table>
+
+## 🚀 Quick Start
 
 ### 1. Install
 
@@ -21,16 +73,11 @@ OpenCode writes memories → Claude Code reads them.
 npm install -g opencode-claude-memory
 ```
 
-This does two things:
-
-- Registers the **plugin** (memory tools + system prompt injection)
-- Places an `opencode` **wrapper** in your global bin that auto-extracts memories after each session
-
-> The wrapper is a drop-in replacement — it finds the real `opencode` binary in `PATH`, runs it normally, then triggers memory extraction in the background when you exit.
+This installs:
+- The **plugin** — memory tools + system prompt injection
+- An `opencode` **wrapper** — auto-extracts memories after each session
 
-### 2. Configure the plugin
-
-Add the plugin to your `opencode.json`:
+### 2. Configure
 
 ```jsonc
 // opencode.json
@@ -41,62 +88,85 @@ Add the plugin to your `opencode.json`:
 
 ### 3. Use
 
-Just run `opencode` as usual. The memory tools are available to the AI agent:
+```bash
+opencode  # just use it as usual
+```
+
+The AI agent can now use memory tools:
 
 - **"Remember that I prefer terse responses"** → saves a `feedback` memory
 - **"What do you remember about me?"** → reads from memory
 - **"Forget the memory about my role"** → deletes a memory
 
-When you exit a session, memories are automatically extracted in the background.
+When you exit, memories are extracted in the background — zero blocking.
 
-### Uninstall
+<details>
+<summary>🗑️ Uninstall</summary>
 
 ```bash
 npm uninstall -g opencode-claude-memory
 ```
 
-This removes both the wrapper and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
+This removes the wrapper and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
+
+</details>
 
-## Auto-Extraction
+## 💡 How It Works
 
-The wrapper:
+```mermaid
+graph LR
+    A[You run opencode] --> B[Wrapper finds real binary]
+    B --> C[Runs opencode normally]
+    C --> D[You exit]
+    D --> E[Get latest session ID]
+    E --> F[Fork session + extract memories]
+    F --> G[Memories saved to ~/.claude/projects/]
+```
 
-1. Finds the real `opencode` binary (skips itself in `PATH`)
-2. Runs it normally with all your arguments
-3. After you exit, finds the most recent session
-4. Forks that session and sends a memory extraction prompt
-5. The extraction runs **in the background** — you're never blocked
+The wrapper is a drop-in replacement that:
 
-### How it works
+1. Scans `PATH` to find the real `opencode` binary (skipping itself)
+2. Runs it with all your arguments
+3. After you exit, forks the session with a memory extraction prompt
+4. Extraction runs **in the background** — you're never blocked
 
-```
-You run `opencode`
-  → wrapper finds real opencode binary (skipping itself in PATH)
-  → runs real opencode with your arguments
-  → you exit
-  → opencode session list --format json -n 1  (get last session)
-  → opencode run -s <id> --fork "<extraction prompt>"  (background)
-  → memories saved to ~/.claude/projects/<project>/memory/
-```
+### What "1:1 Replica" Means
+
+Every core component is ported directly from [Claude Code's source](https://github.com/anthropics/claude-code):
+
+| Component | Source |
+|---|---|
+| `sanitizePath()` + `djb2Hash()` | `utils/sessionStoragePortable.ts` |
+| `findGitRoot()` + worktree resolution | `utils/git.ts` |
+| Memory types & frontmatter format | `commands/memory.ts` |
+| System prompt (types, when to save/skip) | `commands/memory.ts` |
+| Extraction prompt (post-session) | Claude Code's memory extraction agent |
+
+This ensures:
+- `~/.claude/projects/<sanitized>/memory/` paths are **byte-identical** to Claude Code's output
+- Git worktrees resolve to the same canonical root
+- Memory files are interchangeable — no migration needed
+
+## ⚙️ Configuration
 
-### Environment variables
+### Environment Variables
 
 | Variable | Default | Description |
 |---|---|---|
 | `OPENCODE_MEMORY_EXTRACT` | `1` | Set to `0` to disable auto-extraction |
 | `OPENCODE_MEMORY_FOREGROUND` | `0` | Set to `1` to run extraction in foreground (debugging) |
-| `OPENCODE_MEMORY_MODEL` | *(default)* | Override model for extraction (e.g., `anthropic/claude-sonnet-4-20250514`) |
+| `OPENCODE_MEMORY_MODEL` | *(default)* | Override model for extraction |
 | `OPENCODE_MEMORY_AGENT` | *(default)* | Override agent for extraction |
 
 ### Logs
 
 Extraction logs are written to `$TMPDIR/opencode-memory-logs/extract-*.log`.
 
-### Concurrency safety
+### Concurrency Safety
 
 A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks (from crashed processes) are automatically cleaned up.
 
-## Memory Format
+## 📝 Memory Format
 
 Each memory is a Markdown file with YAML frontmatter:
 
@@ -113,7 +183,7 @@ Skip post-action summaries. User reads diffs directly.
 **How to apply:** Don't summarize changes at the end of responses.
 ```
 
-### Memory types
+### Memory Types
 
 | Type | Description |
 |---|---|
@@ -122,44 +192,19 @@ Skip post-action summaries. User reads diffs directly.
 | `project` | Ongoing work context not derivable from code |
 | `reference` | Pointers to external resources |
 
-### Index file
+<details>
+<summary>📄 Index file (MEMORY.md)</summary>
 
-`MEMORY.md` is an index (not content storage). Each entry is one line:
+`MEMORY.md` is an auto-managed index (not content storage). Each entry is one line:
 
 ```markdown
 - [User prefers terse responses](feedback_terse_responses.md) — Skip summaries, user reads diffs
 - [User is a data scientist](user_role.md) — Focus on observability/logging context
 ```
 
-## Claude Code Compatibility
-
-This plugin uses the **exact same path algorithm** as Claude Code:
-
-1. Find the canonical git root (resolves worktrees to their main repo)
-2. Sanitize the path with `sanitizePath()` (Claude Code's algorithm, including `djb2Hash` for long paths)
-3. Store in `~/.claude/projects/<sanitized>/memory/`
-
-This means:
-- Git worktrees of the same repo share the same memory directory
-- The sanitized path matches Claude Code's output exactly
-- Memory files use the same frontmatter format and type taxonomy
-
-## File Structure
-
-```
-opencode-memory/
-├── bin/
-│   └── opencode                # Drop-in wrapper (finds real binary, adds memory extraction)
-├── src/
-│   ├── index.ts                # Plugin entry point (tools + hooks)
-│   ├── memory.ts               # Memory CRUD operations
-│   ├── paths.ts                # Claude-compatible path resolution
-│   └── prompt.ts               # System prompt injection
-├── package.json
-└── tsconfig.json
-```
+</details>
 
-## Tools Reference
+## 🔧 Tools Reference
 
 ### `memory_save`
 
@@ -167,11 +212,11 @@ Save or update a memory.
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `file_name` | string | yes | File name slug (e.g., `user_role`) |
-| `name` | string | yes | Short title |
-| `description` | string | yes | One-line description for relevance matching |
-| `type` | enum | yes | `user`, `feedback`, `project`, or `reference` |
-| `content` | string | yes | Memory content |
+| `file_name` | string | ✅ | File name slug (e.g., `user_role`) |
+| `name` | string | ✅ | Short title |
+| `description` | string | ✅ | One-line description for relevance matching |
+| `type` | enum | ✅ | `user`, `feedback`, `project`, or `reference` |
+| `content` | string | ✅ | Memory content |
 
 ### `memory_delete`
 
@@ -189,6 +234,6 @@ Search memories by keyword across name, description, and content.
 
 Read the full content of a specific memory file.
 
-## License
+## 📄 License
 
-MIT
+[MIT](LICENSE) © [kuitos](https://github.com/kuitos)

package/bin/opencode

@@ -125,6 +125,22 @@ log() {
   echo "[opencode-memory] $*" >&2
 }
 
+has_new_memories() {
+  # Check if any memory file was modified during the session
+  # Checks all projects' memory directories for files newer than the timestamp marker
+  local mem_base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
+  
+  if [ ! -d "$mem_base" ]; then
+    return 1
+  fi
+  
+  # Find any .md file under projects/*/memory/ newer than our timestamp
+  local newer_files
+  newer_files=$(find "$mem_base" -path "*/memory/*.md" -newer "$TIMESTAMP_FILE" 2>/dev/null | head -1)
+  
+  [ -n "$newer_files" ]
+}
+
 get_latest_session_id() {
   local session_json
   session_json=$("$REAL_OPENCODE" session list --format json -n 1 2>/dev/null) || return 1
@@ -157,6 +173,10 @@ release_lock() {
   rm -f "$LOCK_FILE"
 }
 
+cleanup_timestamp() {
+  rm -f "$TIMESTAMP_FILE"
+}
+
 run_extraction() {
   local session_id="$1"
 
@@ -190,12 +210,16 @@ run_extraction() {
 # Main
 # ============================================================================
 
+# Step 0: Create timestamp marker before running opencode
+TIMESTAMP_FILE=$(mktemp)
+
 # Step 1: Run the real opencode with all original arguments, capture exit code
 opencode_exit=0
 "$REAL_OPENCODE" "$@" || opencode_exit=$?
 
 # Step 2: Check if extraction is enabled
 if [ "$EXTRACT_ENABLED" = "0" ]; then
+  cleanup_timestamp
   exit $opencode_exit
 fi
 
@@ -204,11 +228,20 @@ session_id=$(get_latest_session_id)
 
 if [ -z "$session_id" ]; then
   log "No session found, skipping memory extraction"
+  cleanup_timestamp
+  exit $opencode_exit
+fi
+
+# Step 3.5: Check if memories were already written during the session
+if has_new_memories; then
+  log "Main agent already wrote memories during session, skipping extraction"
+  cleanup_timestamp
   exit $opencode_exit
 fi
 
 # Step 4: Acquire lock (prevent concurrent extractions)
 if ! acquire_lock; then
+  cleanup_timestamp
   exit $opencode_exit
 fi
 
@@ -216,11 +249,13 @@ fi
 if [ "$FOREGROUND" = "1" ]; then
   # Foreground mode (for debugging)
   run_extraction "$session_id"
+  cleanup_timestamp
 else
   # Background mode (default) — user isn't blocked
   run_extraction "$session_id" &
   disown
   log "Memory extraction started in background (PID $!)"
+  cleanup_timestamp
 fi
 
 exit $opencode_exit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Cross-session memory plugin for OpenCode — Claude Code compatible, persistent, file-based memory",
   "main": "src/index.ts",
@@ -33,5 +33,9 @@
   },
   "dependencies": {
     "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.11",
+    "@opencode-ai/plugin": "^1.3.10"
   }
 }

package/src/index.ts

@@ -1,15 +1,14 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
 import { buildMemorySystemPrompt } from "./prompt.js"
+import { recallRelevantMemories, formatRecalledMemories } from "./recall.js"
 import {
   saveMemory,
   deleteMemory,
   listMemories,
   searchMemories,
   readMemory,
-  readIndex,
   MEMORY_TYPES,
-  type MemoryType,
 } from "./memory.js"
 import { getMemoryDir } from "./paths.js"
 
@@ -18,7 +17,26 @@ export const MemoryPlugin: Plugin = async ({ worktree }) => {
 
   return {
     "experimental.chat.system.transform": async (_input, output) => {
-      const memoryPrompt = buildMemorySystemPrompt(worktree)
+      let query: string | undefined
+      if (_input && typeof _input === "object") {
+        const messages = (_input as { messages?: unknown }).messages
+        if (Array.isArray(messages)) {
+          const lastUserMsg = [...messages]
+            .reverse()
+            .find((message) =>
+              message && typeof message === "object" && "role" in message && (message as { role?: unknown }).role === "user",
+            )
+
+          if (lastUserMsg && typeof lastUserMsg === "object" && "content" in lastUserMsg) {
+            const content = (lastUserMsg as { content?: unknown }).content
+            query = typeof content === "string" ? content : JSON.stringify(content)
+          }
+        }
+      }
+
+      const recalled = recallRelevantMemories(worktree, query)
+      const recalledSection = formatRecalledMemories(recalled)
+      const memoryPrompt = buildMemorySystemPrompt(worktree, recalledSection)
       output.system.push(memoryPrompt)
     },
 

package/src/memory.ts

@@ -1,6 +1,14 @@
 import { readFileSync, writeFileSync, readdirSync, unlinkSync, existsSync } from "fs"
 import { join, basename } from "path"
-import { getMemoryDir, getMemoryEntrypoint, ENTRYPOINT_NAME } from "./paths.js"
+import {
+  getMemoryDir,
+  getMemoryEntrypoint,
+  ENTRYPOINT_NAME,
+  validateMemoryFileName,
+  MAX_MEMORY_FILES,
+  MAX_MEMORY_FILE_BYTES,
+  FRONTMATTER_MAX_LINES,
+} from "./paths.js"
 
 export const MEMORY_TYPES = ["user", "feedback", "project", "reference"] as const
 export type MemoryType = (typeof MEMORY_TYPES)[number]
@@ -21,11 +29,20 @@ function parseFrontmatter(raw: string): { frontmatter: Record<string, string>; c
     return { frontmatter: {}, content: trimmed }
   }
 
-  const endIndex = trimmed.indexOf("---", 3)
-  if (endIndex === -1) {
+  const lines = trimmed.split("\n")
+  let closingLineIdx = -1
+  for (let i = 1; i < Math.min(lines.length, FRONTMATTER_MAX_LINES); i++) {
+    if (lines[i].trimEnd() === "---") {
+      closingLineIdx = i
+      break
+    }
+  }
+  if (closingLineIdx === -1) {
     return { frontmatter: {}, content: trimmed }
   }
 
+  const endIndex = lines.slice(0, closingLineIdx).join("\n").length + 1
+
   const frontmatterBlock = trimmed.slice(3, endIndex).trim()
   const content = trimmed.slice(endIndex + 3).trim()
 
@@ -61,6 +78,7 @@ export function listMemories(worktree: string): MemoryEntry[] {
     files = readdirSync(memDir)
       .filter((f) => f.endsWith(".md") && f !== ENTRYPOINT_NAME)
       .sort()
+      .slice(0, MAX_MEMORY_FILES)
   } catch {
     return entries
   }
@@ -88,8 +106,9 @@ export function listMemories(worktree: string): MemoryEntry[] {
 }
 
 export function readMemory(worktree: string, fileName: string): MemoryEntry | null {
+  const safeName = validateMemoryFileName(fileName)
   const memDir = getMemoryDir(worktree)
-  const filePath = join(memDir, fileName.endsWith(".md") ? fileName : `${fileName}.md`)
+  const filePath = join(memDir, safeName)
 
   try {
     const rawContent = readFileSync(filePath, "utf-8")
@@ -116,11 +135,16 @@ export function saveMemory(
   type: MemoryType,
   content: string,
 ): string {
+  const safeName = validateMemoryFileName(fileName)
   const memDir = getMemoryDir(worktree)
-  const safeName = fileName.endsWith(".md") ? fileName : `${fileName}.md`
   const filePath = join(memDir, safeName)
 
   const fileContent = `${buildFrontmatter(name, description, type)}\n\n${content.trim()}\n`
+  if (Buffer.byteLength(fileContent, "utf-8") > MAX_MEMORY_FILE_BYTES) {
+    throw new Error(
+      `Memory file content exceeds the ${MAX_MEMORY_FILE_BYTES}-byte limit`,
+    )
+  }
   writeFileSync(filePath, fileContent, "utf-8")
 
   updateIndex(worktree, safeName, name, description)
@@ -129,8 +153,8 @@ export function saveMemory(
 }
 
 export function deleteMemory(worktree: string, fileName: string): boolean {
+  const safeName = validateMemoryFileName(fileName)
   const memDir = getMemoryDir(worktree)
-  const safeName = fileName.endsWith(".md") ? fileName : `${fileName}.md`
   const filePath = join(memDir, safeName)
 
   try {

package/src/paths.ts

@@ -10,6 +10,35 @@ export const ENTRYPOINT_NAME = "MEMORY.md"
 export const MAX_ENTRYPOINT_LINES = 200
 export const MAX_ENTRYPOINT_BYTES = 25_000
 
+export const MAX_MEMORY_FILES = 200
+export const MAX_MEMORY_FILE_BYTES = 40_000
+export const FRONTMATTER_MAX_LINES = 30
+
+export function validateMemoryFileName(fileName: string): string {
+  const base = fileName.endsWith(".md") ? fileName.slice(0, -3) : fileName
+
+  if (base.length === 0) {
+    throw new Error("Memory file name cannot be empty")
+  }
+  if (base.includes("/") || base.includes("\\")) {
+    throw new Error(`Memory file name must not contain path separators: ${fileName}`)
+  }
+  if (base.includes("..")) {
+    throw new Error(`Memory file name must not contain path traversal: ${fileName}`)
+  }
+  if (base.includes("\0")) {
+    throw new Error(`Memory file name must not contain null bytes: ${fileName}`)
+  }
+  if (base.startsWith(".")) {
+    throw new Error(`Memory file name must not start with '.': ${fileName}`)
+  }
+  if (base.toUpperCase() === "MEMORY") {
+    throw new Error(`'MEMORY' is a reserved name and cannot be used as a memory file name`)
+  }
+
+  return `${base}.md`
+}
+
 const MAX_SANITIZED_LENGTH = 200
 
 // Exact copy of Claude Code's djb2Hash() from utils/hash.ts

package/src/prompt.ts

@@ -1,5 +1,5 @@
 import { MEMORY_TYPES } from "./memory.js"
-import { readIndex, truncateEntrypoint, listMemories } from "./memory.js"
+import { readIndex, truncateEntrypoint } from "./memory.js"
 import { getMemoryDir, ENTRYPOINT_NAME } from "./paths.js"
 
 const FRONTMATTER_EXAMPLE = `\`\`\`markdown
@@ -89,7 +89,7 @@ A memory that names a specific function, file, or flag is a claim that it existe
 
 A memory that summarizes repo state is frozen in time. If the user asks about *recent* or *current* state, prefer \`git log\` or reading the code over recalling the snapshot.`
 
-export function buildMemorySystemPrompt(worktree: string): string {
+export function buildMemorySystemPrompt(worktree: string, recalledMemoriesSection?: string): string {
   const memoryDir = getMemoryDir(worktree)
   const indexContent = readIndex(worktree)
 
@@ -139,5 +139,9 @@ export function buildMemorySystemPrompt(worktree: string): string {
     )
   }
 
+  if (recalledMemoriesSection?.trim()) {
+    lines.push("", recalledMemoriesSection)
+  }
+
   return lines.join("\n")
 }

package/src/recall.ts

@@ -0,0 +1,126 @@
+import { statSync } from "fs"
+import { listMemories, type MemoryEntry } from "./memory.js"
+
+const encoder = new TextEncoder()
+
+export type RecalledMemory = {
+  fileName: string
+  name: string
+  type: string
+  description: string
+  content: string
+  ageInDays: number
+}
+
+const MAX_RECALLED_MEMORIES = 5
+const MAX_MEMORY_LINES = 200
+const MAX_MEMORY_BYTES = 4096
+
+function tokenizeQuery(query: string): string[] {
+  return [...new Set(query.toLowerCase().split(/\s+/).map((token) => token.trim()).filter((token) => token.length >= 2))]
+}
+
+function getMemoryMtimeMs(entry: MemoryEntry): number {
+  try {
+    return statSync(entry.filePath).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+function scoreMemory(entry: MemoryEntry, terms: string[]): number {
+  if (terms.length === 0) return 0
+  const haystack = `${entry.name}\n${entry.description}\n${entry.content}`.toLowerCase()
+  let score = 0
+  for (const term of terms) {
+    if (haystack.includes(term)) score += 1
+  }
+  return score
+}
+
+function truncateMemoryContent(content: string): string {
+  const maxLines = content.split("\n").slice(0, MAX_MEMORY_LINES)
+  const lineTruncated = maxLines.join("\n")
+  if (encoder.encode(lineTruncated).length <= MAX_MEMORY_BYTES) {
+    return lineTruncated
+  }
+
+  const lines = lineTruncated.split("\n")
+  const kept: string[] = []
+  let usedBytes = 0
+
+  for (const line of lines) {
+    const candidate = kept.length === 0 ? line : `\n${line}`
+    const candidateBytes = encoder.encode(candidate).length
+    if (usedBytes + candidateBytes > MAX_MEMORY_BYTES) break
+    kept.push(line)
+    usedBytes += candidateBytes
+  }
+
+  return kept.join("\n")
+}
+
+export function recallRelevantMemories(worktree: string, query?: string): RecalledMemory[] {
+  const memories = listMemories(worktree)
+  if (memories.length === 0) return []
+
+  const now = Date.now()
+  const memoriesWithMeta = memories.map((entry) => {
+    const mtimeMs = getMemoryMtimeMs(entry)
+    return {
+      entry,
+      mtimeMs,
+    }
+  })
+
+  const terms = query ? tokenizeQuery(query) : []
+
+  let selected = memoriesWithMeta
+
+  if (terms.length > 0) {
+    const withScores = memoriesWithMeta
+      .map((item) => ({
+        ...item,
+        score: scoreMemory(item.entry, terms),
+      }))
+      .sort((a, b) => b.score - a.score || b.mtimeMs - a.mtimeMs)
+
+    if (withScores.some((item) => item.score > 0)) {
+      selected = withScores
+    }
+  }
+
+  if (selected === memoriesWithMeta) {
+    selected = [...memoriesWithMeta].sort((a, b) => b.mtimeMs - a.mtimeMs)
+  }
+
+  return selected.slice(0, MAX_RECALLED_MEMORIES).map(({ entry, mtimeMs }) => ({
+    fileName: entry.fileName,
+    name: entry.name,
+    type: entry.type,
+    description: entry.description,
+    content: truncateMemoryContent(entry.content),
+    ageInDays: Math.max(0, Math.floor((now - mtimeMs) / (1000 * 60 * 60 * 24))),
+  }))
+}
+
+function formatAgeWarning(ageInDays: number): string {
+  if (ageInDays <= 1) return ""
+  return `\n> ⚠️ This memory is ${ageInDays} days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact.\n`
+}
+
+export function formatRecalledMemories(memories: RecalledMemory[]): string {
+  if (memories.length === 0) return ""
+
+  const sections = memories.map((memory) => {
+    const ageWarning = formatAgeWarning(memory.ageInDays)
+    return `### ${memory.name} (${memory.type})${ageWarning}\n${memory.content}`
+  })
+  return [
+    "## Recalled Memories",
+    "",
+    "The following memories were automatically selected as relevant to this conversation. They may be outdated — verify against current state before relying on them.",
+    "",
+    sections.join("\n\n"),
+  ].join("\n")
+}