feat: add smart recall, path security, file limits, extraction mutual exclusion, and freshness warnings

- Smart recall: keyword-scored prefetch injects top-5 relevant memory content into system prompt
- Path security: validateMemoryFileName rejects traversal, null bytes, hidden files, reserved names
- File limits: 40KB/file, 200 file cap, 30-line frontmatter scan limit
- Extraction mutual exclusion: skip background extraction when main agent already wrote memories
- Freshness warnings: memories older than 1 day show age warning in recalled output
- Add bun-types and @opencode-ai/plugin as devDependencies to fix type errors

Author: kuitos

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,23 +228,34 @@ 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
 
 # Step 5: Run extraction
 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.json

@@ -33,5 +33,9 @@
   },
   "dependencies": {
     "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.11",
+    "@opencode-ai/plugin": "^1.3.10"
   }
 }

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)
     },
 

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 {

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

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")
 }