opencode-team-memory 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0
+
+- Initial release
+- `role_memory_save`, `role_memory_load`, `role_memory_clear` tools
+- Compaction hook for automatic context injection
+- Cross-role memory reading support
+- Data versioning (`version` field in context.json)
+- Toggle on/off via `.omo/.team-memory-disabled` marker file

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,210 @@
+# opencode-team-memory
+
+Persistent role-based memory for OpenCode + Oh-My-OpenCode(OmO) Team Mode.  
+Context survives across sessions, Team Mode runs, and compaction.
+
+## Problem
+
+OmO Team Mode members are ephemeral — they die when the run ends (default: 120 min).  
+Next session, every role starts from zero. No persistent Engineer context, no Tester NG history,  
+no Director decision trail.
+
+## Solution
+
+Three tools that read/write role context to the filesystem:
+
+| Tool | Purpose |
+|---|---|
+| `role_memory_save` | Persist decisions, NG history, scope, active files, handoff target |
+| `role_memory_load` | Restore context from previous sessions (own role or cross-read others) |
+| `role_memory_clear` | Reset memory for a fresh start |
+
+Stored per-role at `<project>/.omo/team-memory/{role}/context.json`.  
+Override with `OPENCODE_TEAM_MEMORY_DIR` env var.
+
+Compaction hook injects compact summaries automatically — long sessions keep context.
+
+## Enable / Disable
+
+Toggle without editing config files. Restart `opencode` after switching.
+
+**Disable**:
+```bash
+touch .omo/.team-memory-disabled
+```
+
+**Enable**:
+```bash
+rm .omo/.team-memory-disabled
+```
+
+Or register as custom commands in `opencode.json`:
+
+```jsonc
+{
+  "command": {
+    "memory-on": {
+      "description": "Enable team memory plugin",
+      "command": "rm -f .omo/.team-memory-disabled && echo 'Team memory enabled (restart opencode)'"
+    },
+    "memory-off": {
+      "description": "Disable team memory plugin",
+      "command": "touch .omo/.team-memory-disabled && echo 'Team memory disabled (restart opencode)'"
+    }
+  }
+}
+```
+
+Then type `/memory-off` or `/memory-on` in the TUI.
+
+## Install
+
+```bash
+bun add -d opencode-team-memory
+# or: npm install --save-dev opencode-team-memory
+```
+
+Register in `opencode.json`:
+
+```jsonc
+{
+  "plugin": ["opencode-team-memory"]
+}
+```
+
+## Team Member Prompt Template
+
+Add this to each member's prompt in `.omo/teams/{name}/config.json`:
+
+```markdown
+## Persistent Memory Protocol
+
+### On session start (MANDATORY)
+role_memory_load(role="<your-role>") before ANY work.
+Cross-read other roles as needed (e.g. Tester reads Engineer's memory).
+
+### On session end / handoff (MANDATORY)
+role_memory_save(role="<your-role>", raw="...", previous_decisions=[...])
+
+### Handoff
+Before passing to the next role, set handoff_to="<next-role>" in your save.
+```
+
+### Role-specific prompts
+
+<details>
+<summary>Director (Lead / Sisyphus)</summary>
+
+```
+You are the Director. Load memory first.
+- previous_decisions: carry forward prior judgments
+- excluded_scope: NEVER touch these areas
+- On save: record every decision (adopt/reject/defer + reason)
+- Do NOT dive into implementation details — delegate to Engineer
+```
+</details>
+
+<details>
+<summary>Engineer (deep / hephaestus)</summary>
+
+```
+You are the Engineer. Load memory first.
+- ng_history: check for repeated bugs before coding
+- active_files: be extra careful with these
+- On save: record "what was committed, what changed, unresolved concerns"
+- On handoff to Tester: put "what to test, preconditions, repro steps" in raw
+- On handoff to Director: put "completed scope, known limits, unhandled edge cases" in raw
+- Do NOT make spec decisions alone — confirm with Director via team_send_message
+```
+</details>
+
+<details>
+<summary>Tester (quick / unspecified-low)</summary>
+
+```
+You are the Tester. Load your memory AND Engineer's memory first.
+- ng_history: extract verification points from prior failures
+- On save: record test results (OK/NG), test angles covered
+- On NG: team_send_message to Engineer with "NG item, expected, actual, repro steps"
+  AND role_memory_save with ng_history update
+- On OK: team_send_message to Director
+  AND role_memory_save with full test results
+- Do NOT fix issues yourself — always bounce back to Engineer
+- Do NOT approve with "probably fine" — verify expected vs actual
+```
+</details>
+
+<details>
+<summary>Designer (visual-engineering + frontend-ui-ux)</summary>
+
+```
+You are the Designer. Load memory first.
+- previous_decisions: recall prior UI choices and rejections
+- ng_history: watch for recurring UX issues
+- On save: record "adopted patterns, rejected alternatives, mobile feel, empty states"
+- On handoff to Director: put "recommended UI, alternatives + tradeoffs, decisions needed" in raw
+- On handoff to Engineer: put "adopted UI pattern, state transitions, edge case displays" in raw
+- Do NOT let implementation difficulty skew UI judgment — Director decides
+- Be specific: "vague discomfort" is not actionable
+```
+</details>
+
+## Cross-role memory reading
+
+Tester should read Engineer's memory for context:
+
+```
+role_memory_load(role="engineer")  // what was implemented, preconditions
+role_memory_load(role="tester")    // own context
+```
+
+Designer should read Director's memory:
+
+```
+role_memory_load(role="director")  // scope, goals, explicit exclusions
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `OPENCODE_TEAM_MEMORY_DIR` | `<project>/.omo/team-memory` | Storage directory. **Warning**: If set globally, multiple projects share the same memory. Use per-project values or keep the default. |
+
+## Stored data structure
+
+```typescript
+interface MemoryEntry {
+  version: number               // schema version (for future migration)
+  role: string
+  project: string
+  last_updated: string
+  previous_decisions: string[]  // max 50 entries
+  ng_history: string[]          // max 50 entries
+  confirmed_scope: string[]
+  excluded_scope: string[]
+  active_files: string[]
+  handoff_to: string            // target role for next handoff
+  raw_entries: string[]         // max 50, load returns last 5
+}
+```
+
+## Troubleshooting
+
+**Tools not visible in Team members**  
+If OmO Team members can't see `role_memory_*` tools, the plugin tools may not be exposed to subagent sessions.  
+Workaround: wrap the same logic in an MCP server. A companion MCP package is planned.
+
+**Stale context across runs**  
+Run `role_memory_clear(role="engineer")` to wipe and start fresh.
+
+## Versioning
+
+- **MAJOR**: Data structure breaking changes (field removal, type change)
+- **MINOR**: New tool, new optional field (backward compatible)
+- **PATCH**: Bug fixes, doc updates
+
+The `version` field in `context.json` enables future migration of old data.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,107 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+import { readFile, writeFile, mkdir, access } from "node:fs/promises"
+import { join } from "node:path"
+import { ALL_ROLES, EMPTY_MEMORY, type MemoryEntry, type Role, type SaveInput } from "./types"
+import { merge, format, formatCompact, formatSaveResult } from "./memory"
+
+function getMemoryBase(directory: string): string {
+  return process.env.OPENCODE_TEAM_MEMORY_DIR || join(directory, ".omo", "team-memory")
+}
+
+function getDisabledMarker(directory: string): string {
+  return join(directory, ".omo", ".team-memory-disabled")
+}
+
+function isENOENT(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT"
+}
+
+export const TeamMemoryPlugin: Plugin = async ({ directory }) => {
+  const marker = getDisabledMarker(directory)
+  try {
+    await access(marker)
+    return {}
+  } catch {
+    // marker file does not exist — plugin is enabled
+  }
+  const base = getMemoryBase(directory)
+
+  async function load(role: Role): Promise<MemoryEntry | null> {
+    try {
+      const text = await readFile(join(base, role, "context.json"), "utf-8")
+      return JSON.parse(text) as MemoryEntry
+    } catch (err: unknown) {
+      if (isENOENT(err)) {
+        return null
+      }
+      throw err
+    }
+  }
+
+  async function save(input: SaveInput): Promise<MemoryEntry> {
+    const dir = join(base, input.role)
+    await mkdir(dir, { recursive: true })
+    const existing = await load(input.role)
+    const merged = merge(existing, input, directory)
+    await writeFile(join(dir, "context.json"), JSON.stringify(merged, null, 2))
+    return merged
+  }
+
+  return {
+    tool: {
+      role_memory_save: tool({
+        description: "Save persistent role context — survives across sessions and Team Mode runs",
+        args: {
+          role: tool.schema.enum(ALL_ROLES),
+          previous_decisions: tool.schema.array(tool.schema.string()).optional(),
+          ng_history: tool.schema.array(tool.schema.string()).optional(),
+          confirmed_scope: tool.schema.array(tool.schema.string()).optional(),
+          excluded_scope: tool.schema.array(tool.schema.string()).optional(),
+          active_files: tool.schema.array(tool.schema.string()).optional(),
+          handoff_to: tool.schema.string().optional(),
+          raw: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          const m = await save(args as SaveInput)
+          return formatSaveResult(m)
+        },
+      }),
+
+      role_memory_load: tool({
+        description: "Load persistent role context from previous sessions. Call for your own role at session start, or cross-read other roles as needed",
+        args: {
+          role: tool.schema.enum(ALL_ROLES),
+        },
+        async execute(args) {
+          return format(await load(args.role as Role), args.role as Role)
+        },
+      }),
+
+      role_memory_clear: tool({
+        description: "Clear all persistent memory for a role — use when starting fresh work",
+        args: {
+          role: tool.schema.enum(ALL_ROLES),
+        },
+        async execute(args) {
+          const dir = join(base, args.role as Role)
+          await mkdir(dir, { recursive: true })
+          await writeFile(join(dir, "context.json"), JSON.stringify(EMPTY_MEMORY(args.role as Role, directory), null, 2))
+          return `✓ Cleared all memory for '${args.role}'`
+        },
+      }),
+    },
+
+    "experimental.session.compacting": async (_input, output) => {
+      for (const role of ALL_ROLES) {
+        try {
+          const entry = await load(role)
+          if (entry) {
+            output.context.push(formatCompact(entry))
+          }
+        } catch {
+          // skip roles with no saved memory
+        }
+      }
+    },
+  }
+}

package/memory.ts

@@ -0,0 +1,99 @@
+import { type MemoryEntry, type SaveInput, CURRENT_VERSION, EMPTY_MEMORY, type Role } from "./types"
+
+const MAX_KEEP = 50
+const RAW_LOAD_LIMIT = 5
+
+export function merge(existing: MemoryEntry | null, input: SaveInput, project: string): MemoryEntry {
+  const now = new Date().toISOString()
+
+  if (!existing) {
+    return {
+      ...EMPTY_MEMORY(input.role, project),
+      last_updated: now,
+      previous_decisions: (input.previous_decisions || []).slice(-MAX_KEEP),
+      ng_history: (input.ng_history || []).slice(-MAX_KEEP),
+      confirmed_scope: input.confirmed_scope || [],
+      excluded_scope: input.excluded_scope || [],
+      active_files: input.active_files || [],
+      handoff_to: input.handoff_to !== undefined ? input.handoff_to : "",
+      raw_entries: input.raw ? [input.raw] : [],
+    }
+  }
+
+  const base = migrate(existing)
+
+  const append = (a: string[], b?: string[]): string[] =>
+    [...a, ...(b || [])].slice(-MAX_KEEP)
+
+  return {
+    ...base,
+    last_updated: now,
+    previous_decisions: append(base.previous_decisions, input.previous_decisions),
+    ng_history: append(base.ng_history, input.ng_history),
+    confirmed_scope: input.confirmed_scope || base.confirmed_scope,
+    excluded_scope: input.excluded_scope || base.excluded_scope,
+    active_files: input.active_files || base.active_files,
+    handoff_to: input.handoff_to !== undefined ? input.handoff_to : base.handoff_to,
+    raw_entries: input.raw
+      ? append(base.raw_entries, [input.raw])
+      : base.raw_entries,
+  }
+}
+
+function migrate(entry: MemoryEntry): MemoryEntry {
+  if (entry.version >= CURRENT_VERSION) return entry
+  return { ...entry, version: CURRENT_VERSION }
+}
+
+export function format(entry: MemoryEntry | null, role: Role): string {
+  if (!entry) return `No saved context for role '${role}'. This is a fresh start.`
+
+  const raw = entry.raw_entries.slice(-RAW_LOAD_LIMIT)
+
+  return [
+    `=== PERSISTENT CONTEXT: ${role} ===`,
+    `Project: ${entry.project}`,
+    `Last updated: ${entry.last_updated}`,
+    ``,
+    `## Previous Decisions (${entry.previous_decisions.length} total, showing last ${Math.min(entry.previous_decisions.length, RAW_LOAD_LIMIT)})`,
+    ...entry.previous_decisions.slice(-RAW_LOAD_LIMIT).map((d, i) => `${i + 1}. ${d}`),
+    ``,
+    `## NG History (${entry.ng_history.length} total, showing last ${Math.min(entry.ng_history.length, RAW_LOAD_LIMIT)})`,
+    ...entry.ng_history.slice(-RAW_LOAD_LIMIT).map((n, i) => `${i + 1}. ${n}`),
+    ``,
+    `## Confirmed Scope`,
+    ...entry.confirmed_scope.map((s) => `- ${s}`),
+    ``,
+    `## Excluded Scope (DO NOT TOUCH)`,
+    ...entry.excluded_scope.map((s) => `- ${s}`),
+    ``,
+    `## Active Files`,
+    ...entry.active_files.map((f) => `- ${f}`),
+    ``,
+    entry.handoff_to ? `## Handoff Target → ${entry.handoff_to}` : "",
+    ``,
+    `## Raw Context Entries (${entry.raw_entries.length} total, showing last ${raw.length})`,
+    ...raw.map((r, i) => `--- Entry ${entry.raw_entries.length - raw.length + i + 1} ---\n${r}`),
+  ].join("\n")
+}
+
+export function formatCompact(entry: MemoryEntry | null): string {
+  if (!entry) return "(no memory)"
+
+  return [
+    `## Team Memory: ${entry.role}`,
+    `Decisions: ${entry.previous_decisions.slice(-3).join("; ") || "none"}`,
+    `Recent NG: ${entry.ng_history.slice(-2).join("; ") || "none"}`,
+    `Scope: confirmed=[${entry.confirmed_scope.join(", ")}] excluded=[${entry.excluded_scope.join(", ")}]`,
+    `Files: ${entry.active_files.join(", ") || "none"}`,
+  ].join("\n")
+}
+
+export function formatSaveResult(entry: MemoryEntry): string {
+  return [
+    `✓ Saved context for '${entry.role}'`,
+    `  Decisions: ${entry.previous_decisions.length} | NG: ${entry.ng_history.length}`,
+    `  Scope: ${entry.confirmed_scope.length} confirmed / ${entry.excluded_scope.length} excluded`,
+    entry.handoff_to ? `  Next: → ${entry.handoff_to}` : "",
+  ].join("\n")
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "opencode-team-memory",
+  "version": "1.0.0",
+  "description": "Persistent role-based memory for OpenCode/OmO Team Mode — survives across sessions and runs",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "types.ts",
+    "memory.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "prepublishOnly": "bun test"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "oh-my-opencode",
+    "oh-my-openagent",
+    "team-mode",
+    "multi-agent",
+    "memory",
+    "persistence"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KenKozuma/opencode-team-memory"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  }
+}

package/types.ts

@@ -0,0 +1,44 @@
+export const CURRENT_VERSION = 1
+
+export type Role = "engineer" | "tester" | "designer" | "director"
+
+export const ALL_ROLES: Role[] = ["engineer", "tester", "designer", "director"]
+
+export interface MemoryEntry {
+  version: number
+  role: Role
+  project: string
+  last_updated: string
+  previous_decisions: string[]
+  ng_history: string[]
+  confirmed_scope: string[]
+  excluded_scope: string[]
+  active_files: string[]
+  handoff_to: string
+  raw_entries: string[]
+}
+
+export const EMPTY_MEMORY = (role: Role, project: string): MemoryEntry => ({
+  version: CURRENT_VERSION,
+  role,
+  project,
+  last_updated: new Date().toISOString(),
+  previous_decisions: [],
+  ng_history: [],
+  confirmed_scope: [],
+  excluded_scope: [],
+  active_files: [],
+  handoff_to: "",
+  raw_entries: [],
+})
+
+export interface SaveInput {
+  role: Role
+  previous_decisions?: string[]
+  ng_history?: string[]
+  confirmed_scope?: string[]
+  excluded_scope?: string[]
+  active_files?: string[]
+  handoff_to?: string
+  raw?: string
+}