openrecall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Artur Sidorenko
+
+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

@@ -0,0 +1,145 @@
+# OpenRecall
+
+> Cross-session memory plugin for [OpenCode](https://github.com/opencode-ai/opencode) with full-text search, tagging, and auto-recall
+
+OpenRecall gives your OpenCode sessions persistent memory. It stores important findings, decisions, and code patterns and makes them searchable across sessions using SQLite FTS5 with BM25 ranking.
+
+## Features
+
+- **12 LLM tools** — Store, search, update, delete, list, tag, link, refresh, export, import, cleanup, and stats
+- **Auto-recall** — Automatically injects relevant memories into the system prompt when a session starts
+- **Auto-extraction** — Detects preferences, bug fixes, and conventions from tool outputs
+- **Full-text search** — FTS5 with BM25 ranking, stop word removal, and query sanitization
+- **Relevance decay** — Older, unaccessed memories naturally rank lower (90-day half-life)
+- **Deduplication** — Prevents storing duplicate or near-duplicate memories
+- **Tagging** — Organize memories with tags, search by tag
+- **Memory linking** — Create relationships between memories (related, supersedes, contradicts, extends)
+- **Global memories** — Store knowledge that applies across all projects
+- **Import/export** — Back up and migrate memories as JSON
+- **Database maintenance** — Auto-optimization, cleanup tools, memory limits
+
+## Installation
+
+```bash
+bun add openrecall
+```
+
+Add to your OpenCode config (`opencode.json`):
+
+```json
+{
+  "plugins": ["openrecall"]
+}
+```
+
+## Configuration
+
+Configure via `opencode.json` under `plugins.openrecall`:
+
+```json
+{
+  "plugins": {
+    "openrecall": {
+      "autoRecall": true,
+      "autoExtract": true,
+      "searchLimit": 10,
+      "maxMemories": 0,
+      "globalMemories": false
+    }
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dbPath` | string | `~/.local/share/opencode/openrecall.db` | Database file path |
+| `autoRecall` | boolean | `true` | Auto-inject relevant memories on session start |
+| `autoExtract` | boolean | `true` | Auto-extract patterns from tool outputs |
+| `searchLimit` | number | `10` | Default max search results |
+| `maxMemories` | number | `0` | Memory limit (0 = unlimited) |
+| `globalMemories` | boolean | `false` | Enable cross-project global memories |
+
+## Tools
+
+### Core
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Store a memory with content, category, tags, and global flag |
+| `memory_search` | Full-text search with BM25 ranking and relevance decay |
+| `memory_update` | Update content, category, or source of an existing memory |
+| `memory_delete` | Delete a memory by ID |
+| `memory_list` | List recent memories with category/scope filters |
+| `memory_stats` | Show total count, category breakdown, and DB size |
+
+### Organization
+
+| Tool | Description |
+|------|-------------|
+| `memory_tag` | Add, remove, list tags; list all tags; search by tag |
+| `memory_link` | Create/remove relationships between memories |
+| `memory_refresh` | Boost a memory's relevance to prevent decay |
+
+### Infrastructure
+
+| Tool | Description |
+|------|-------------|
+| `memory_export` | Export memories to versioned JSON |
+| `memory_import` | Import memories from JSON with conflict handling |
+| `memory_cleanup` | FTS optimization, purge old memories, vacuum DB |
+
+## How It Works
+
+### Search
+
+Memories are indexed in a SQLite FTS5 virtual table. Queries are sanitized (special characters removed, stop words stripped) and matched using BM25 ranking. Results are then re-ranked with a time decay factor:
+
+```
+final_score = bm25_score * (1 / (1 + age_days * 0.0077))
+```
+
+Frequently accessed memories get an additional boost based on `access_count`.
+
+### Auto-recall
+
+On the first message in a new session, OpenRecall searches for memories relevant to the user's message and injects the top results into the system prompt. Falls back to showing recent memories if no search matches.
+
+### Auto-extraction
+
+The `tool.execute.after` hook monitors tool outputs for patterns:
+- **Preferences**: "always use...", "never do...", "I prefer..."
+- **Bug fixes**: "fixed by...", "the issue was..."
+- **Conventions**: "project uses...", "convention is..."
+
+Extracted memories are rate-limited (max 20 per session) and deduplicated.
+
+### Deduplication
+
+Before storing, content is checked against existing memories:
+- **Exact match** (case-insensitive, whitespace-normalized): returns existing memory
+- **Near-duplicate** (Jaccard similarity > 0.8): updates existing memory with newer content
+- Use `force: true` to bypass deduplication
+
+## Data Storage
+
+- Database: `~/.local/share/opencode/openrecall.db` (configurable)
+- All data is stored locally — nothing is sent externally
+- Uses SQLite WAL mode for concurrent read performance
+- Auto-maintenance runs every 7 days (FTS optimization, limit enforcement)
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "openrecall",
+  "version": "0.1.0",
+  "description": "Cross-session memory plugin for OpenCode with full-text search, tagging, and auto-recall",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun test && bun run typecheck"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "memory",
+    "cross-session",
+    "semantic-search",
+    "fts5",
+    "sqlite",
+    "ai",
+    "llm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ASidorenkoCode/openrecall.git"
+  },
+  "homepage": "https://github.com/ASidorenkoCode/openrecall",
+  "bugs": {
+    "url": "https://github.com/ASidorenkoCode/openrecall/issues"
+  },
+  "license": "MIT",
+  "author": "ASidorenkoCode",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,268 @@
+import { storeMemory } from "./memory"
+import { isDbAvailable } from "./db"
+import * as fs from "fs"
+import * as path from "path"
+
+// Key project files to scan on startup
+const KEY_FILES = [
+  "README.md",
+  "CONTRIBUTING.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "package.json",
+  "tsconfig.json",
+  "opencode.json",
+  ".claude/CLAUDE.md",
+  "CLAUDE.md",
+  ".cursorrules",
+  ".github/CODEOWNERS",
+]
+
+// Max content length per memory chunk
+const MAX_CHUNK = 400
+
+// Track which files have been scanned this process lifetime
+const scannedFiles = new Set<string>()
+
+interface ExtractionCounter {
+  count: number
+  extracting: boolean
+}
+
+const sessionCounters = new Map<string, ExtractionCounter>()
+
+export function getCounter(sessionID: string): ExtractionCounter {
+  let counter = sessionCounters.get(sessionID)
+  if (!counter) {
+    counter = { count: 0, extracting: false }
+    sessionCounters.set(sessionID, counter)
+  }
+  return counter
+}
+
+export function incrementCounter(sessionID: string): number {
+  const counter = getCounter(sessionID)
+  counter.count++
+  return counter.count
+}
+
+export function shouldTrigger(sessionID: string, interval: number): boolean {
+  const counter = getCounter(sessionID)
+  return counter.count > 0 && counter.count % interval === 0 && !counter.extracting
+}
+
+export function clearCounter(sessionID: string): void {
+  sessionCounters.delete(sessionID)
+}
+
+/**
+ * Scan key project files on startup and store their content as memories.
+ * Only stores files that haven't been scanned yet or have been modified since last scan.
+ */
+export function scanProjectFiles(directory: string, projectId: string): void {
+  if (!isDbAvailable()) return
+
+  let stored = 0
+
+  for (const relPath of KEY_FILES) {
+    try {
+      const fullPath = path.join(directory, relPath)
+      if (!fs.existsSync(fullPath)) continue
+
+      const stat = fs.statSync(fullPath)
+      if (!stat.isFile()) continue
+      // Skip large files (> 50KB)
+      if (stat.size > 50 * 1024) continue
+
+      // Use mtime as cache key to avoid re-scanning unchanged files
+      const cacheKey = `${fullPath}:${stat.mtimeMs}`
+      if (scannedFiles.has(cacheKey)) continue
+      scannedFiles.add(cacheKey)
+
+      const content = fs.readFileSync(fullPath, "utf-8")
+      if (!content.trim()) continue
+
+      // For package.json, extract key info
+      if (relPath === "package.json") {
+        storePackageJsonMemory(content, projectId, relPath)
+        stored++
+        continue
+      }
+
+      // Store file content in chunks
+      stored += storeFileChunks(content, projectId, relPath)
+    } catch (e) {
+      // Silent fail per file — don't break startup
+    }
+  }
+
+  // Also scan for recently modified files via git
+  try {
+    stored += scanRecentGitFiles(directory, projectId)
+  } catch {
+    // Git might not be available
+  }
+
+  if (stored > 0) {
+    console.error(`[OpenRecall] Startup scan: stored ${stored} file memories`)
+  }
+}
+
+function storePackageJsonMemory(content: string, projectId: string, filePath: string): void {
+  try {
+    const pkg = JSON.parse(content)
+    const parts: string[] = []
+
+    if (pkg.name) parts.push(`name: ${pkg.name}`)
+    if (pkg.description) parts.push(`description: ${pkg.description}`)
+    if (pkg.scripts) {
+      const scripts = Object.keys(pkg.scripts).join(", ")
+      parts.push(`scripts: ${scripts}`)
+    }
+    if (pkg.dependencies) {
+      const deps = Object.keys(pkg.dependencies).slice(0, 15).join(", ")
+      parts.push(`dependencies: ${deps}`)
+    }
+    if (pkg.devDependencies) {
+      const devDeps = Object.keys(pkg.devDependencies).slice(0, 10).join(", ")
+      parts.push(`devDependencies: ${devDeps}`)
+    }
+    if (pkg.type) parts.push(`type: ${pkg.type}`)
+    if (pkg.main || pkg.module) parts.push(`entry: ${pkg.main || pkg.module}`)
+
+    const summary = parts.join(" | ")
+    if (summary.length > 10) {
+      storeMemory({
+        content: summary.slice(0, MAX_CHUNK),
+        category: "discovery",
+        projectId,
+        source: `file-scan: ${filePath}`,
+        tags: ["project-config", "package.json"],
+      })
+    }
+  } catch {
+    // Invalid JSON, skip
+  }
+}
+
+function storeFileChunks(content: string, projectId: string, filePath: string): number {
+  // Split by sections (headers in markdown, or double newlines)
+  const sections = content.split(/\n#{1,3}\s+|\n\n/).filter((s) => s.trim().length > 20)
+  let stored = 0
+
+  // Store up to 5 chunks per file to avoid flooding
+  const maxChunks = 5
+  for (let i = 0; i < Math.min(sections.length, maxChunks); i++) {
+    const chunk = sections[i]!.trim()
+    if (chunk.length < 20) continue
+
+    const truncated = chunk.length > MAX_CHUNK ? chunk.slice(0, MAX_CHUNK) + "..." : chunk
+
+    try {
+      storeMemory({
+        content: truncated,
+        category: "discovery",
+        projectId,
+        source: `file-scan: ${filePath} (section ${i + 1})`,
+        tags: ["file-content", path.basename(filePath).toLowerCase()],
+      })
+      stored++
+    } catch {
+      // Dedup or other error, skip
+    }
+  }
+
+  return stored
+}
+
+function scanRecentGitFiles(directory: string, projectId: string): number {
+  // Use git to find recently modified tracked files (last 7 days)
+  const { execSync } = require("child_process")
+  let stored = 0
+
+  try {
+    const result = execSync("git log --diff-filter=M --name-only --pretty=format: --since=7.days.ago HEAD", {
+      cwd: directory,
+      encoding: "utf-8",
+      timeout: 5000,
+    })
+
+    const files = [...new Set(
+      result.split("\n").filter((f: string) => f.trim().length > 0),
+    )].slice(0, 20)
+
+    if (files.length > 0) {
+      const summary = `Recently modified files (last 7 days): ${files.join(", ")}`
+      storeMemory({
+        content: summary.slice(0, MAX_CHUNK),
+        category: "discovery",
+        projectId,
+        source: "file-scan: git-recent",
+        tags: ["git", "recent-changes"],
+      })
+      stored++
+    }
+  } catch {
+    // Git not available or failed
+  }
+
+  return stored
+}
+
+/**
+ * Extract file knowledge from tool execution.
+ * Called from tool.execute.after to track what files the LLM reads/edits.
+ */
+export function extractFileKnowledge(
+  toolName: string,
+  args: any,
+  output: string,
+  sessionId: string,
+  projectId: string,
+): void {
+  if (!isDbAvailable()) return
+
+  // Only track file-related tools
+  const fileTools = new Set(["read", "edit", "write", "glob", "grep"])
+  if (!fileTools.has(toolName)) return
+
+  try {
+    const filePath = args?.filePath || args?.file_path || args?.path
+    if (!filePath || typeof filePath !== "string") return
+
+    if (toolName === "read") {
+      // Store file content summary from read output
+      if (!output || output.length < 30) return
+
+      // Take the first ~400 chars as a content preview
+      const preview = output.slice(0, MAX_CHUNK)
+      const basename = path.basename(filePath)
+
+      storeMemory({
+        content: `File ${basename}: ${preview}`,
+        category: "discovery",
+        projectId,
+        sessionId,
+        source: `tool-read: ${filePath}`,
+        tags: ["file-content", basename.toLowerCase()],
+      })
+    } else if (toolName === "edit" || toolName === "write") {
+      // Store what was edited/written
+      const basename = path.basename(filePath)
+      const editInfo = args?.old_string
+        ? `Edited ${basename}: replaced content in ${filePath}`
+        : `Wrote to ${basename}: ${filePath}`
+
+      storeMemory({
+        content: editInfo.slice(0, MAX_CHUNK),
+        category: "discovery",
+        projectId,
+        sessionId,
+        source: `tool-${toolName}: ${filePath}`,
+        tags: ["file-edit", basename.toLowerCase()],
+      })
+    }
+  } catch {
+    // Silent fail
+  }
+}

package/src/client.ts

@@ -0,0 +1,16 @@
+import type { PluginInput } from "@opencode-ai/plugin"
+
+type SdkClient = PluginInput["client"]
+
+let sdkClient: SdkClient | null = null
+
+export function initClient(client: SdkClient) {
+  sdkClient = client
+}
+
+export function getClient(): SdkClient {
+  if (!sdkClient) {
+    throw new Error("OpenRecall: SDK client not initialized")
+  }
+  return sdkClient
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import { join } from "path"
+import { homedir } from "os"
+
+export const DEFAULT_CATEGORIES = [
+  "decision",
+  "pattern",
+  "debugging",
+  "preference",
+  "convention",
+  "discovery",
+  "general",
+] as const
+
+export type Category = (typeof DEFAULT_CATEGORIES)[number]
+
+export interface OpenRecallConfig {
+  dbPath: string
+  categories: string[]
+  maxMemories: number
+  autoRecall: boolean
+  autoExtract: boolean
+  searchLimit: number
+  globalMemories: boolean
+  agentModel: string
+}
+
+function getDefaultDbPath(): string {
+  const home = homedir()
+  const xdgData = process.env.XDG_DATA_HOME || join(home, ".local", "share")
+  return join(xdgData, "opencode", "openrecall.db")
+}
+
+const DEFAULTS: OpenRecallConfig = {
+  dbPath: getDefaultDbPath(),
+  categories: [...DEFAULT_CATEGORIES],
+  maxMemories: 0, // 0 = unlimited
+  autoRecall: true,
+  autoExtract: true,
+  searchLimit: 10,
+  globalMemories: false,
+  agentModel: "",
+}
+
+let currentConfig: OpenRecallConfig = { ...DEFAULTS }
+
+export function getConfig(): OpenRecallConfig {
+  return currentConfig
+}
+
+export function initConfig(userConfig?: Partial<OpenRecallConfig>): OpenRecallConfig {
+  currentConfig = { ...DEFAULTS }
+
+  if (userConfig) {
+    if (userConfig.dbPath) currentConfig.dbPath = userConfig.dbPath
+    if (userConfig.categories && userConfig.categories.length > 0) {
+      currentConfig.categories = userConfig.categories
+    }
+    if (typeof userConfig.maxMemories === "number") {
+      currentConfig.maxMemories = userConfig.maxMemories
+    }
+    if (typeof userConfig.autoRecall === "boolean") {
+      currentConfig.autoRecall = userConfig.autoRecall
+    }
+    if (typeof userConfig.autoExtract === "boolean") {
+      currentConfig.autoExtract = userConfig.autoExtract
+    }
+    if (typeof userConfig.searchLimit === "number" && userConfig.searchLimit > 0) {
+      currentConfig.searchLimit = userConfig.searchLimit
+    }
+    if (typeof userConfig.globalMemories === "boolean") {
+      currentConfig.globalMemories = userConfig.globalMemories
+    }
+    if (typeof userConfig.agentModel === "string" && userConfig.agentModel.trim()) {
+      currentConfig.agentModel = userConfig.agentModel.trim()
+    }
+  }
+
+  return currentConfig
+}

package/src/db.ts

@@ -0,0 +1,93 @@
+import { Database } from "bun:sqlite"
+import { mkdirSync, existsSync } from "fs"
+import { dirname } from "path"
+import { getConfig } from "./config"
+import { migrations } from "./migrations"
+
+let db: Database | null = null
+let initFailed = false
+
+export function isDbAvailable(): boolean {
+  return db !== null && !initFailed
+}
+
+export function getDb(): Database {
+  if (db) return db
+
+  if (initFailed) {
+    throw new Error("OpenRecall: database initialization previously failed")
+  }
+
+  try {
+    const dbPath = getConfig().dbPath
+    const dir = dirname(dbPath)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+
+    db = new Database(dbPath)
+
+    db.run("PRAGMA journal_mode = WAL")
+    db.run("PRAGMA synchronous = NORMAL")
+    db.run("PRAGMA busy_timeout = 5000")
+    db.run("PRAGMA foreign_keys = ON")
+
+    runMigrations(db)
+
+    return db
+  } catch (e) {
+    initFailed = true
+    db = null
+    console.error("[OpenRecall] Database initialization failed:", e)
+    throw e
+  }
+}
+
+function runMigrations(db: Database) {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      version INTEGER PRIMARY KEY,
+      description TEXT NOT NULL,
+      applied_at INTEGER NOT NULL DEFAULT (unixepoch())
+    )
+  `)
+
+  const applied = new Set(
+    (
+      db.prepare("SELECT version FROM _migrations").all() as {
+        version: number
+      }[]
+    ).map((r) => r.version),
+  )
+
+  for (const migration of migrations) {
+    if (applied.has(migration.version)) continue
+
+    db.run("BEGIN")
+    try {
+      migration.up(db)
+      db.run(
+        "INSERT INTO _migrations (version, description) VALUES (?, ?)",
+        [migration.version, migration.description],
+      )
+      db.run("COMMIT")
+    } catch (e) {
+      db.run("ROLLBACK")
+      throw new Error(
+        `Migration ${migration.version} (${migration.description}) failed: ${e}`,
+      )
+    }
+  }
+}
+
+export function closeDb() {
+  if (db) {
+    try {
+      db.run("PRAGMA optimize")
+    } catch {
+      // ignore optimization errors on close
+    }
+    db.close()
+    db = null
+  }
+}