opencode-memory 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kris
+
+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,118 @@
+# Simple Memory Plugin for OpenCode
+
+[![npm version](https://img.shields.io/npm/v/@knikolov/opencode-plugin-simple-memory)](https://www.npmjs.com/package/@knikolov/opencode-plugin-simple-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A persistent memory plugin for [OpenCode](https://opencode.ai) that enables the AI assistant to remember context across sessions.
+
+## Setup
+
+1. Add the plugin to your [OpenCode config](https://opencode.ai/docs/config/):
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["@knikolov/opencode-plugin-simple-memory"]
+   }
+   ```
+
+2. Start using memory commands in your conversations.
+
+Memories are stored in `.opencode/memory/` as daily logfmt files.
+
+## Updating
+
+> [!WARNING]
+> OpenCode does NOT auto-update plugins.
+
+To get the latest version, clear the cached plugin and let OpenCode reinstall it:
+
+```bash
+# Remove the plugin from cache
+rm -rf ~/.cache/opencode/node_modules/@knikolov/opencode-plugin-simple-memory
+
+# Run OpenCode to trigger reinstall
+opencode
+```
+
+## Tools
+
+The plugin provides five tools:
+
+| Tool | Description |
+|------|-------------|
+| `memory_remember` | Store a new memory |
+| `memory_recall` | Retrieve memories by scope, type, or search query |
+| `memory_update` | Update an existing memory |
+| `memory_forget` | Delete a memory (with audit logging) |
+| `memory_list` | List all scopes and types for discovery |
+
+## Memory Types
+
+- `decision` - Architectural or design decisions
+- `learning` - Things learned during development
+- `preference` - User or project preferences
+- `blocker` - Current blockers or issues
+- `context` - General context information
+- `pattern` - Recurring patterns or conventions
+
+## Example Usage
+
+```
+User: Remember that my name is Kris
+
+AI: [calls memory_remember with type="context", scope="user", 
+     content="User's name is Kris"]
+    
+    I've stored that your name is Kris.
+
+User: My preferred programming language is Erlang
+
+AI: [calls memory_remember with type="preference", scope="user", 
+     content="Preferred programming language is Erlang"]
+    
+    Got it! I've noted that your preferred programming language is Erlang.
+
+User: What do you know about me?
+
+AI: [calls memory_recall with scope="user"]
+    
+    Here's what I know about you:
+    - Your name is Kris
+    - Your preferred programming language is Erlang
+
+User: Actually, I prefer Elixir now.
+
+AI: [calls memory_update with type="preference", scope="user", 
+     content="Preferred programming language is Elixir"]
+    
+    Updated your language preference to Elixir.
+
+User: Forget my language preference
+
+AI: [calls memory_forget with type="preference", scope="user", 
+     reason="User requested removal"]
+    
+    Done. I've removed your language preference from memory.
+```
+
+## Local Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/cnicolov/opencode-plugin-simple-memory.git
+cd opencode-plugin-simple-memory
+bun install
+```
+
+Point your OpenCode config to the local checkout via a `file://` URL:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["file:///absolute/path/to/opencode-plugin-simple-memory"]
+}
+```
+
+Replace `/absolute/path/to/opencode-plugin-simple-memory` with your actual path.

package/index.ts

@@ -0,0 +1,2 @@
+export { MemoryPlugin } from "./src/index";
+export { MemoryPlugin as default } from "./src/index";

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "opencode-memory",
+  "module": "index.ts",
+  "version": "1.0.0",
+  "author": "knikolov",
+  "repository": "https://github.com/shuans/opencode-memory",
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.153",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,359 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+const MEMORY_DIR = "~/.config/opencode/memory"
+
+const getMemoryFile = () => {
+  const date = new Date().toISOString().split("T")[0]
+  return Bun.file(`${MEMORY_DIR}/${date}.logfmt`)
+}
+
+const ensureDir = async () => {
+  const dir = Bun.file(MEMORY_DIR)
+  if (!(await dir.exists())) {
+    await Bun.$`mkdir -p ${MEMORY_DIR}`
+  }
+}
+
+interface Memory {
+  ts: string
+  type: string
+  scope: string
+  content: string
+  issue?: string
+  tags?: string[]
+}
+
+const parseLine = (line: string): Memory | null => {
+  const tsMatch = line.match(/ts=([^\s]+)/)
+  const typeMatch = line.match(/type=([^\s]+)/)
+  const scopeMatch = line.match(/scope=([^\s]+)/)
+  const contentMatch = line.match(/content="([^"]*(?:\\"[^"]*)*)"/)
+  const issueMatch = line.match(/issue=([^\s]+)/)
+  const tagsMatch = line.match(/tags=([^\s]+)/)
+
+  if (!tsMatch?.[1] || !typeMatch?.[1] || !scopeMatch?.[1]) return null
+
+  return {
+    ts: tsMatch[1],
+    type: typeMatch[1],
+    scope: scopeMatch[1],
+    content: contentMatch?.[1]?.replace(/\\"/g, '"') || "",
+    issue: issueMatch?.[1],
+    tags: tagsMatch?.[1]?.split(","),
+  }
+}
+
+const formatMemory = (m: Memory): string => {
+  const date = m.ts.split("T")[0]
+  const tags = m.tags?.length ? ` [${m.tags.join(", ")}]` : ""
+  const issue = m.issue ? ` (${m.issue})` : ""
+  return `[${date}] ${m.type}/${m.scope}: ${m.content}${issue}${tags}`
+}
+
+const scoreMatch = (memory: Memory, words: string[]): number => {
+  const searchable = `${memory.type} ${memory.scope} ${memory.content} ${memory.tags?.join(" ") || ""}`.toLowerCase()
+  let score = 0
+  for (const word of words) {
+    if (searchable.includes(word)) score++
+    if (memory.scope.toLowerCase() === word) score += 2
+    if (memory.type.toLowerCase() === word) score += 2
+  }
+  return score
+}
+
+const remember = tool({
+  description: "Store a memory (decision, learning, preference, blocker, context, pattern)",
+  args: {
+    type: tool.schema
+      .enum(["decision", "learning", "preference", "blocker", "context", "pattern"])
+      .describe("Type of memory"),
+    scope: tool.schema.string().describe("Scope/area (e.g., auth, api, mobile)"),
+    content: tool.schema.string().describe("The memory content"),
+    issue: tool.schema.string().optional().describe("Related GitHub issue (e.g., #51)"),
+    tags: tool.schema.array(tool.schema.string()).optional().describe("Additional tags"),
+  },
+  async execute(args) {
+    await ensureDir()
+
+    const ts = new Date().toISOString()
+    const issue = args.issue ? ` issue=${args.issue}` : ""
+    const tags = args.tags?.length ? ` tags=${args.tags.join(",")}` : ""
+    const content = args.content.replace(/"/g, '\\"')
+    const line = `ts=${ts} type=${args.type} scope=${args.scope} content="${content}"${issue}${tags}\n`
+
+    const file = getMemoryFile()
+    const existing = (await file.exists()) ? await file.text() : ""
+    await Bun.write(file, existing + line)
+
+    return `Remembered: ${args.type} in ${args.scope}`
+  },
+})
+
+const getAllMemories = async (): Promise<Memory[]> => {
+  const glob = new Bun.Glob("*.logfmt")
+  const files = await Array.fromAsync(glob.scan(MEMORY_DIR))
+
+  if (!files.length) return []
+
+  const lines: string[] = []
+  for (const filename of files) {
+    if (filename === "deletions.logfmt") continue // skip audit log
+    const file = Bun.file(`${MEMORY_DIR}/${filename}`)
+    const text = await file.text()
+    lines.push(...text.trim().split("\n").filter(Boolean))
+  }
+
+  return lines.map(parseLine).filter((m): m is Memory => m !== null)
+}
+
+const logDeletion = async (memory: Memory, reason: string) => {
+  await ensureDir()
+  const ts = new Date().toISOString()
+  const content = memory.content.replace(/"/g, '\\"')
+  const originalTs = memory.ts
+  const issue = memory.issue ? ` issue=${memory.issue}` : ""
+  const tags = memory.tags?.length ? ` tags=${memory.tags.join(",")}` : ""
+  const escapedReason = reason.replace(/"/g, '\\"')
+  const line = `ts=${ts} action=deleted original_ts=${originalTs} type=${memory.type} scope=${memory.scope} content="${content}" reason="${escapedReason}"${issue}${tags}\n`
+
+  const file = Bun.file(`${MEMORY_DIR}/deletions.logfmt`)
+  const existing = (await file.exists()) ? await file.text() : ""
+  await Bun.write(file, existing + line)
+}
+
+const recall = tool({
+  description: "Retrieve memories by scope, type, or search query",
+  args: {
+    scope: tool.schema.string().optional().describe("Filter by scope"),
+    type: tool.schema
+      .enum(["decision", "learning", "preference", "blocker", "context", "pattern"])
+      .optional()
+      .describe("Filter by type"),
+    query: tool.schema.string().optional().describe("Search term (space-separated words, matches any)"),
+    limit: tool.schema.number().optional().describe("Max results (default 20)"),
+  },
+  async execute(args) {
+    let results = await getAllMemories()
+
+    if (!results.length) return "No memories found"
+
+    const totalCount = results.length
+
+    if (args.scope) {
+      results = results.filter((m) => m.scope === args.scope || m.scope.includes(args.scope!))
+    }
+    if (args.type) {
+      results = results.filter((m) => m.type === args.type)
+    }
+
+    if (args.query) {
+      const words = args.query.toLowerCase().split(/\s+/).filter(Boolean)
+      const scored = results
+        .map((m) => ({ memory: m, score: scoreMatch(m, words) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+      results = scored.map((x) => x.memory)
+    }
+
+    const filteredCount = results.length
+    const limit = args.limit || 20
+    const limited = results.slice(-limit)
+
+    if (!limited.length) return "No matching memories"
+
+    const header = filteredCount > limit
+      ? `Found ${filteredCount} memories (showing last ${limit} of ${totalCount} total)\n\n`
+      : filteredCount !== totalCount
+        ? `Found ${filteredCount} memories (${totalCount} total)\n\n`
+        : `Found ${filteredCount} memories\n\n`
+
+    return header + limited.map(formatMemory).join("\n")
+  },
+})
+
+const update = tool({
+  description: "Update an existing memory by scope and type (finds matching memory and updates its content)",
+  args: {
+    scope: tool.schema.string().describe("Scope of memory to update"),
+    type: tool.schema
+      .enum(["decision", "learning", "preference", "blocker", "context", "pattern"])
+      .describe("Type of memory"),
+    content: tool.schema.string().describe("The new content for the memory"),
+    query: tool.schema.string().optional().describe("Search term to find specific memory if multiple exist"),
+    issue: tool.schema.string().optional().describe("Update related GitHub issue (e.g., #51)"),
+    tags: tool.schema.array(tool.schema.string()).optional().describe("Update tags"),
+  },
+  async execute(args) {
+    const glob = new Bun.Glob("*.logfmt")
+    const files = await Array.fromAsync(glob.scan(MEMORY_DIR))
+
+    if (!files.length) return "No memory files found"
+
+    // Find matching memories
+    const matches: { memory: Memory; filepath: string; lineIndex: number }[] = []
+
+    for (const filename of files) {
+      if (filename === "deletions.logfmt") continue
+      const filepath = `${MEMORY_DIR}/${filename}`
+      const file = Bun.file(filepath)
+      const text = await file.text()
+      const lines = text.split("\n")
+
+      lines.forEach((line, lineIndex) => {
+        const memory = parseLine(line)
+        if (!memory) return
+        if (memory.scope === args.scope && memory.type === args.type) {
+          matches.push({ memory, filepath, lineIndex })
+        }
+      })
+    }
+
+    if (matches.length === 0) {
+      return `No memories found for ${args.type} in ${args.scope}`
+    }
+
+    // If multiple matches and query provided, filter by query
+    let target: typeof matches[number] | undefined = matches[0]
+    if (matches.length > 1) {
+      if (args.query) {
+        const words = args.query.toLowerCase().split(/\s+/).filter(Boolean)
+        const scored = matches
+          .map((m) => ({ ...m, score: scoreMatch(m.memory, words) }))
+          .filter((x) => x.score > 0)
+          .sort((a, b) => b.score - a.score)
+
+        if (scored.length === 0) {
+          return `Found ${matches.length} memories for ${args.type}/${args.scope}, but none matched query "${args.query}". Use recall to see all matches.`
+        }
+        target = scored[0]
+      } else {
+        return `Found ${matches.length} memories for ${args.type}/${args.scope}. Provide a query to select which one to update, or use recall to see all matches.`
+      }
+    }
+
+    if (!target) {
+      return `No memories found for ${args.type} in ${args.scope}`
+    }
+
+    // Log the old version before updating
+    await logDeletion(target.memory, `Updated to: ${args.content}`)
+
+    // Update the memory
+    const file = Bun.file(target.filepath)
+    const text = await file.text()
+    const lines = text.split("\n")
+
+    const ts = new Date().toISOString()
+    const issue = args.issue !== undefined ? args.issue : target.memory.issue
+    const tags = args.tags !== undefined ? args.tags : target.memory.tags
+    const issueStr = issue ? ` issue=${issue}` : ""
+    const tagsStr = tags?.length ? ` tags=${tags.join(",")}` : ""
+    const content = args.content.replace(/"/g, '\\"')
+    const newLine = `ts=${ts} type=${args.type} scope=${args.scope} content="${content}"${issueStr}${tagsStr}`
+
+    lines[target.lineIndex] = newLine
+    await Bun.write(target.filepath, lines.join("\n"))
+
+    return `Updated ${args.type} in ${args.scope}: "${args.content}"`
+  },
+})
+
+const listMemories = tool({
+  description: "List all unique scopes and types in memory for discovery",
+  args: {},
+  async execute() {
+    const memories = await getAllMemories()
+
+    if (!memories.length) return "No memories found"
+
+    const scopes = new Map<string, number>()
+    const types = new Map<string, number>()
+    const scopeTypes = new Map<string, Set<string>>()
+
+    for (const m of memories) {
+      scopes.set(m.scope, (scopes.get(m.scope) || 0) + 1)
+      types.set(m.type, (types.get(m.type) || 0) + 1)
+      if (!scopeTypes.has(m.scope)) scopeTypes.set(m.scope, new Set())
+      scopeTypes.get(m.scope)!.add(m.type)
+    }
+
+    const lines: string[] = []
+    lines.push(`Total memories: ${memories.length}`)
+    lines.push("")
+    lines.push("Scopes:")
+    for (const [scope, count] of [...scopes.entries()].sort((a, b) => b[1] - a[1])) {
+      const typeList = [...scopeTypes.get(scope)!].join(", ")
+      lines.push(`  ${scope}: ${count} (${typeList})`)
+    }
+    lines.push("")
+    lines.push("Types:")
+    for (const [type, count] of [...types.entries()].sort((a, b) => b[1] - a[1])) {
+      lines.push(`  ${type}: ${count}`)
+    }
+
+    return lines.join("\n")
+  },
+})
+
+const forget = tool({
+  description: "Delete a memory by scope and type (removes matching lines from all memory files, logs deletion for audit)",
+  args: {
+    scope: tool.schema.string().describe("Scope of memory to delete"),
+    type: tool.schema
+      .enum(["decision", "learning", "preference", "blocker", "context", "pattern"])
+      .describe("Type of memory"),
+    reason: tool.schema.string().describe("Why this is being deleted (for audit purposes)"),
+  },
+  async execute(args) {
+    const glob = new Bun.Glob("*.logfmt")
+    const files = await Array.fromAsync(glob.scan(MEMORY_DIR))
+
+    if (!files.length) return "No memory files found"
+
+    let deleted = 0
+    const deletedMemories: Memory[] = []
+
+    for (const filename of files) {
+      if (filename === "deletions.logfmt") continue // skip audit log
+      const filepath = `${MEMORY_DIR}/${filename}`
+      const file = Bun.file(filepath)
+      const text = await file.text()
+      const lines = text.split("\n")
+      const filtered = lines.filter((line) => {
+        const memory = parseLine(line)
+        if (!memory) return true
+        if (memory.scope === args.scope && memory.type === args.type) {
+          deleted++
+          deletedMemories.push(memory)
+          return false
+        }
+        return true
+      })
+      if (filtered.length !== lines.length) {
+        await Bun.write(filepath, filtered.join("\n"))
+      }
+    }
+
+    // Log all deletions to audit file
+    for (const memory of deletedMemories) {
+      await logDeletion(memory, args.reason)
+    }
+
+    if (deleted === 0) return `No memories found for ${args.type} in ${args.scope}`
+    return `Deleted ${deleted} ${args.type} memory(s) from ${args.scope}. Reason: ${args.reason}\nDeletions logged to ${MEMORY_DIR}/deletions.logfmt`
+  },
+})
+
+export const MemoryPlugin: Plugin = async (_ctx) => {
+  return {
+    tool: {
+      memory_remember: remember,
+      memory_recall: recall,
+      memory_update: update,
+      memory_forget: forget,
+      memory_list: listMemories,
+    },
+  }
+}
+
+export default MemoryPlugin