opencode-self-improvement 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Bogartz
+
+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,3 +1,123 @@
-# Temporary Holding Version
+# Opencode-Self-Improvement
+
+Durable memory for opencode, plus a one-command per-repo setup.
+
+## Why is this here?
+
+LLMs waste a lot of tokens reading and re-reading your code and asking you for clarifications you've already given it. This tells it to store those decisions so the next time you hit a similar part of the code, it knows more and gets to the answer faster. 
+## What you get
+
+- **`memory_*` tools** — remember facts, decisions, and commands the agent should
+  keep across sessions (`memory_init`, `memory_remember`, `memory_recall`,
+  `memory_update`, `memory_forget`, `memory_list`, `memory_undo`,
+  `memory_evidence`).
+- **`/repo-init`** — for each repo: indexes the code graph and remembers the
+  test/build commands, keyed to the git head. The command installs itself; no
+  setup beyond the plugin.
+- Automatically de-dupes similar memories and avoids contradictions by searching for existing memories before saving new ones.
+- Automatically looks for insights when you complete the verification gates (tests, linting, etc)
+- Always defaults to memories first before sending a prompt to the LLM, which saves tokens! 
+
+## Quick start
+
+1. Add the plugin to your Opencode config (see install below) and restart Opencode.
+2. In any repo, run:
+
+   ```
+   /repo-init
+   ```
+
+That's it. Rerun `/repo-init force` after a refactor to refresh.
+
+## How to install
+
+Add a `plugin` entry to your opencode config —
+`~/.config/opencode/opencode.json` (global) or any project `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-self-improvement@0.1.0"]
+}
+```
+
+Opencode installs the package (and its dependencies) automatically with Bun at
+startup. Quit and restart opencode; the plugin loads and `/repo-init` installs
+itself. Nothing else to do.
+
+Pin the exact version (as above). An unpinned entry resolves `@latest` exactly
+once and is never re-resolved afterwards, so it silently sticks. To update,
+bump the version in the config and restart. On Opencode v2 you can also manage
+it with the CLI:
+
+```sh
+opencode plugin add opencode-self-improvement@0.1.0
+opencode plugin update opencode-self-improvement
+```
+
+<details>
+<summary>Install from a clone (development)</summary>
+
+```sh
+git clone https://github.com/abogartz/opencode-self-improvement.git
+cd opencode-self-improvement
+bun install
+```
+
+Then point the `plugin` entry at the local file instead:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["/full/path/to/opencode-self-improvement/index.ts"]
+}
+```
+
+After changes, `git pull` and restart opencode.
+
+</details>
+
+## Code graph (optional)
+
+`/repo-init` also indexes the repo into a queryable knowledge graph via
+[`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp),
+pinned to `0.11.0` as an optional dependency, so opencode's auto-install at
+startup brings it in. If a copy is already on your `PATH`, that one is used
+instead; override explicitly with `OPENCODE_CBM_BIN=/path/to/codebase-memory-mcp`.
+When no graph binary is available, `/repo-init` still records scripts and the
+init stamp — the graph is a lookup bonus, not a requirement (see below).
+
+Manual install of the pinned binary (if you want it globally):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
+```
+
+## First use
+
+Run `/repo-init` once in every repo you work in. It:
+
+- indexes the repo's code graph (`codebase-memory-mcp`), only when missing or forced;
+- stores the test/lint/typecheck commands as memories;
+- writes an init stamp tied to the current git head.
+
+Ongoing use is just the memory tools. Ask the agent to remember something and it
+sticks across sessions; check what's stored with `memory_list`, refine with
+`memory_update`, retract with `memory_forget`, roll back with `memory_undo`.
+
+## Admin Tool
+
+Editing and deleting memories is easy!
+
+Run `bun memory-view` in your terminal and visit  http://127.0.0.1:8787 in your browser. 
+
+## Troubleshooting
+
+| Problem | Fix |
+| --- | --- |
+| `memory_*` tools not available | The plugin didn't load. Restart opencode and check the `plugin` entry in your config. |
+| `/repo-init` missing from the command list | The self-install couldn't write to `~/.config/opencode/commands/` (e.g. read-only config dir). Create it, restart, or just ask the model to "init memory for this repo" — it calls the same tool. |
+| Init says `Graph: unavailable` | `codebase-memory-mcp` couldn't start (not installed, or its once-only download is blocked). Install pinned `0.11.0` via the one-liner above, or point `OPENCODE_CBM_BIN` at the binary. Scripts are still remembered without it. |
+| Stale plugin after an update | Bump the pinned version in the `plugin` entry (or `opencode plugin update opencode-self-improvement` on v2) and restart opencode. |
+| Reset all memories | Delete `~/.config/opencode/memory/`. |
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/command/repo-init.md

@@ -0,0 +1,16 @@
+---
+description: Initialize the code graph and build/test memories for this repo
+---
+Initialize this repository for durable memory and graph-backed work.
+
+1. Ensure the codebase-memory graph is indexed for this repository.
+2. Re-derive build/lint/test/typecheck commands and write them as pattern
+   memories (scope = this repo name).
+3. Store an init stamp keyed on git HEAD so future sessions can cheaply tell
+   whether the repo has drifted.
+
+Call the `memory_init` tool to do this. If the user typed arguments (e.g.
+"force"), pass them through: set `force: true` when $ARGUMENTS mentions force,
+otherwise run a fresh idempotent init.
+
+Then report concisely: graph status, scripts recorded, and the stamp head.

package/index.ts

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

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "opencode-self-improvement",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Durable memory for opencode: remember facts, decisions, and commands across sessions, plus a one-command per-repo setup (/repo-init).",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "module": "index.ts",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alex Bogartz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abogartz/opencode-self-improvement.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abogartz/opencode-self-improvement/issues"
+  },
+  "homepage": "https://github.com/abogartz/opencode-self-improvement#readme",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "memory",
+    "ai-agent"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "command",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.31"
+  },
+  "optionalDependencies": {
+    "codebase-memory-mcp": "0.11.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "memory-view": "bun run src/viewer/server.ts"
+  }
 }

package/src/blocklist.ts

@@ -0,0 +1,56 @@
+// Human intervention for poisoned/stale memory. A blocked memory is
+// still retained on disk (never destroyed) but is filtered out of every read
+// path: recall, the injected digest and contextual pull, and the viewer's
+// active list. Blocklist lives at <memoryRoot>/blocklist.logfmt so a recursive
+// memory scan must never pick it up.
+import { join } from "node:path";
+import { memoryRoot } from "./config.ts";
+import { appendLog, formatLine, parseLine, readLines } from "./logfmt.ts";
+
+const BLOCKLIST_FILENAME = "blocklist.logfmt";
+
+export interface BlockEntry {
+  ts: string;
+  reason: string;
+  blocked_at: string;
+}
+
+export function blocklistFile(): string {
+  return join(memoryRoot(), BLOCKLIST_FILENAME);
+}
+
+export async function blockedEntries(): Promise<BlockEntry[]> {
+  const lines = await readLines(blocklistFile());
+  const out: BlockEntry[] = [];
+  for (const line of lines) {
+    const f = parseLine(line);
+    if (!f || typeof f.ts !== "string") continue;
+    out.push({
+      ts: f.ts,
+      reason: typeof f.reason === "string" ? f.reason : "",
+      blocked_at: typeof f.blocked_at === "string" ? f.blocked_at : "",
+    });
+  }
+  return out;
+}
+
+export async function blockedTs(): Promise<Set<string>> {
+  return new Set((await blockedEntries()).map((b) => b.ts));
+}
+
+export async function addBlock(ts: string, reason: string): Promise<string> {
+  if (!reason.trim()) throw new Error("reason is required to block a memory");
+  await appendLog(blocklistFile(), formatLine({ ts, reason, blocked_at: new Date().toISOString() }));
+  return ts;
+}
+
+export async function removeBlock(ts: string): Promise<boolean> {
+  const file = Bun.file(blocklistFile());
+  if (!(await file.exists())) return false;
+  const kept = (await file.text()).split("\n").filter((l) => {
+    const f = parseLine(l);
+    return !(f && f.ts === ts);
+  });
+  await Bun.write(blocklistFile(), kept.join("\n") + (kept.length ? "\n" : ""));
+  return true;
+}

package/src/command.ts

@@ -0,0 +1,25 @@
+// Self-installs the /repo-init slash command as part of plugin load, so users
+// never run a terminal command to set up init. The command markdown ships in
+// the package (command/repo-init.md) and is mirrored idempotently
+// (write-if-missing; never overwrites a user's edits). Failures are swallowed —
+// a missing command degrades to "ask the model to call memory_init".
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { commandsDir } from "./config.ts";
+
+const SOURCE = join(dirname(fileURLToPath(import.meta.url)), "..", "command", "repo-init.md");
+
+export async function ensureInitCommand(): Promise<string | null> {
+  try {
+    const target = join(commandsDir(), "repo-init.md");
+    if (existsSync(target)) return null;
+    const text = await Bun.file(SOURCE).text();
+    await mkdir(commandsDir(), { recursive: true });
+    await Bun.write(target, text);
+    return target;
+  } catch {
+    return null;
+  }
+}

package/src/config.ts

@@ -0,0 +1,60 @@
+// Store paths for the self-improvement harness. Everything lives OUTSIDE any
+// repository (invariant I2): under ~/.config/opencode/memory by default, or
+// under $OPENCODE_MEMORY_DIR when set (tests use this for hermetic runs).
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function memoryRoot(): string {
+  return (
+    process.env.OPENCODE_MEMORY_DIR ||
+    join(homedir(), ".config", "opencode", "memory")
+  );
+}
+
+// Where the plugin mirrors its own slash command (/repo-init). Written once at
+// load (write-if-missing), so no manual setup is needed after install.
+export function commandsDir(): string {
+  return (
+    process.env.OPENCODE_COMMANDS_DIR ||
+    join(homedir(), ".config", "opencode", "commands")
+  );
+}
+
+export function evidenceDir(): string {
+  return join(memoryRoot(), "evidence");
+}
+
+export function snapshotDir(): string {
+  return join(memoryRoot(), "snapshots");
+}
+
+export function canonicalFile(): string {
+  return join(memoryRoot(), "canonical.logfmt");
+}
+
+export function deletionsFile(): string {
+  return join(memoryRoot(), "deletions.logfmt");
+}
+
+export function dateStr(d: Date = new Date()): string {
+  return d.toISOString().split("T")[0];
+}
+
+// Optional live-graph binary. When present the resolver cross-checks the local
+// source scan against the codebase-memory-mcp file graph; when absent the local
+// scan alone is authoritative (install-from-scratch requirement).
+// Discovery order: OPENCODE_CBM_BIN override, an already-installed global on
+// PATH (matches a running MCP session's build), then the pinned npm copy
+// (codebase-memory-mcp is an optionalDependency of this package).
+export function cbmBin(): string | undefined {
+  if (process.env.OPENCODE_CBM_BIN) return process.env.OPENCODE_CBM_BIN;
+  if (Bun.which("codebase-memory-mcp")) return undefined;
+  try {
+    const resolved = import.meta.resolve("codebase-memory-mcp/bin.js");
+    if (resolved.startsWith("file://")) return fileURLToPath(resolved);
+  } catch {
+    // optional graph dependency not installed; PATH lookup still applies
+  }
+  return undefined;
+}

package/src/evidence.ts

@@ -0,0 +1,50 @@
+// Evidence log writer. One logfmt line per event, appended in hook order to
+// ~/.config/opencode/memory/evidence/<date>.logfmt. Evidence is DATA, never
+// chat (invariant I3) and never inside a repo (I2).
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { dateStr, evidenceDir } from "./config.ts";
+import { appendLog, formatLine } from "./logfmt.ts";
+import { getCurrent } from "./state.ts";
+
+export type EvidenceEvent = string;
+
+export async function record(
+  ev: EvidenceEvent,
+  fields: Record<string, unknown> = {},
+  includeContext = true,
+): Promise<void> {
+  const { sid, call } = getCurrent();
+  const line = formatLine({
+    ev,
+    ts: new Date().toISOString(),
+    ...(includeContext ? { sid, call } : {}),
+    ...fields,
+  });
+  await appendLog(join(evidenceDir(), `${dateStr()}.logfmt`), line);
+}
+
+export function contentHash(content: string): string {
+  return createHash("sha1").update(content).digest("hex").slice(0, 12);
+}
+
+export function chainId(): string {
+  return createHash("sha1")
+    .update(`${Date.now()}-${Math.random()}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
+export async function recordWriteBlocked(
+  gate: number,
+  reason: string,
+  flags: string[],
+  chain?: string,
+): Promise<void> {
+  await record("write_blocked", {
+    gate,
+    reason,
+    flags: `[${flags.join(",")}]`,
+    ...(chain ? { chain } : {}),
+  });
+}