opencode-codex-memory 0.4.11 → 0.6.0

package/README.md

@@ -27,10 +27,10 @@ from there everything lives under `~/.local/share/opencode/`, so you can read it
 grep it, edit it, or delete it like anything else you own. Nothing leaves your
 machine beyond the model calls OpenCode already makes.
 
-If you *do* also use the Codex CLI: the plugin can share memory with Codex in
-both directions — what one assistant learns on your machine, the other picks
-up. Off by default, one config flag per direction; see
-[Sharing memory with the Codex CLI](#sharing-memory-with-the-codex-cli).
+If you *do* also use the Codex CLI or Claude Code on the same machine: the
+plugin can bring their memories in (and, for Codex, push ours back). Off by
+default — see [Sharing memory with the Codex CLI](#sharing-memory-with-the-codex-cli)
+and [Importing memory from Claude Code](#importing-memory-from-claude-code).
 
 ## Why
 
@@ -52,7 +52,7 @@ If you want the mental model before the details, jump to
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.4.11"]
+  "plugin": ["opencode-codex-memory@0.6.0"]
 }
 ```
 
@@ -191,6 +191,20 @@ them — it's yours. (The `memories/` folder also holds a few working files and
 an internal `.git/` the plugin uses for change tracking; `memory_reset` wipes
 those too.)
 
+### Backup and restore
+
+Back up the whole OpenCode data directory while OpenCode is stopped. The
+SQLite database and `memories/` workspace are a pair: restoring only one can
+leave job state, Git baseline, and memory files out of sync. Include hidden
+files, especially `memories/.git/`, and SQLite sidecars such as `memory.db-wal`
+or `memory.db-shm` when present.
+
+The directory is `$XDG_DATA_HOME/opencode` when `XDG_DATA_HOME` is set,
+otherwise `~/.local/share/opencode`. Copy that whole directory to a dated
+backup location. To restore, stop OpenCode, replace the current `opencode/`
+data directory with the backup copy, then start OpenCode again. Do not restore
+while OpenCode is running or copy only `memory.db` or only `memories/`.
+
 ## Privacy & safety
 
 - **Local only.** There is no remote storage option to enable, by accident or
@@ -233,13 +247,14 @@ Codex's `[memories]` config so the two stay easy to compare:
 | `max_rollouts_per_startup` | `2` | Max sessions extracted per pass |
 | `max_unused_days` | `30` | Prune memories unused for this long |
 | `codex_interop` | `{ "import": false, "export": false }` | Two-way memory exchange with a local Codex CLI (see below) |
+| `claude_import` | `{ "enabled": false }` | One-way import of Claude Code project memories (see below) |
 
 To set options, turn the plugin entry into a `[name, options]` pair:
 
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.11", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.6.0", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -291,36 +306,150 @@ explicitly, so they win over an agent-level `model`.
 
 ### Sharing memory with the Codex CLI
 
-If you switch between OpenCode and OpenAI's Codex CLI on the same machine, the
-plugin can exchange consolidated memories with Codex — in either or both
-directions:
+If you use OpenCode and the Codex CLI on the same machine, turn this on so each
+side can pick up what the other already learned. **Either or both directions.**
+Off by default; no changes to Codex's own config are required.
+
+**Enable both directions:**
+
+```json
+{
+  "plugin": [
+    [
+      "opencode-codex-memory@0.6.0",
+      { "codex_interop": { "import": true, "export": true } }
+    ]
+  ]
+}
+```
+
+- **Import:** on each consolidation pass here, durable memory from Codex is
+  merged into this plugin's store (tagged so you can tell it came from Codex).
+- **Export:** after a successful consolidation here, this plugin's memory is
+  offered to Codex; Codex merges it on *its* next consolidation pass.
+
+**Options** (all under `codex_interop`):
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `import` | `false` | Bring Codex's consolidated memory into OpenCode. |
+| `export` | `false` | Offer this plugin's consolidated memory to Codex. |
+| `codex_home` | `$CODEX_HOME`, else `~/.codex` | Where the Codex CLI keeps its data. Set this if you use a non-default location. |
+
+**Notes**
+
+- Export only runs once Codex has created its own memory workspace
+  (`$CODEX_HOME/memories`). Until then, import/export quietly do nothing for
+  the missing side.
+- Codex's own files are never rewritten in place — export only adds a side
+  channel Codex already knows how to read.
+- Both sides tag origin (`[from codex]` / `[from opencode]`) and skip the other
+  tag on re-import, so the same facts don't bounce back and forth.
+- Safe to combine with `claude_import`. Check status with `memory_inspect`
+  (`codex_interop:` section).
+
+**Turning it off**
+
+Setting `import` / `export` back to `false` (or removing `codex_interop`) only
+stops further sync. Already merged memory stays in this plugin's store, and any
+staging copies stay on disk (harmless while import is off). The last export left
+in Codex stays until Codex consolidates it away or you remove it there.
+
+To drop the local staging copies too: turn import off first, then delete
+`extensions/codex_import/` under the plugin memory directory (see
+[Where your data lives](#where-your-data-lives)). Leave import off — if you turn
+it back on, the next pass will recreate them from Codex. After a deletion, the
+next consolidation can treat the missing files as a signal to drop entries that
+only came from that import.
+
+### Importing memory from Claude Code
+
+If you use Claude Code as well as OpenCode, turn this on so OpenCode can learn
+from the project memories Claude already keeps on your machine. **One-way only**
+(Claude → OpenCode); nothing is written back into Claude. Off by default.
+
+**Enable everything Claude has:**
 
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.11", { "codex_interop": { "import": true, "export": true } }]
+    ["opencode-codex-memory@0.6.0", { "claude_import": { "enabled": true } }]
   ]
 }
 ```
 
-- `import` copies Codex's consolidated `MEMORY.md` / `memory_summary.md` into a
-  memory extension (`extensions/codex_import/`) before each consolidation pass.
-  The consolidator merges what's new, tagging it `[from codex]`.
-- `export` copies this plugin's consolidated memory into Codex's memory
-  workspace as an extension (`extensions/opencode_import/`) after each
-  successful consolidation, together with instructions for Codex's own
-  consolidator. Codex picks it up on its next consolidation — no Codex
-  configuration needed. Nothing is exported until Codex's memory feature has
-  created `$CODEX_HOME/memories`, and Codex's own files are never modified.
-  (After a `memory_reset` here, the last export stays in Codex until your
-  next successful consolidation replaces it.)
-- `codex_home` overrides where Codex lives (default: `$CODEX_HOME`, else
-  `~/.codex`).
-
-Both sides mark imported content with a provenance tag (`[from codex]` /
-`[from opencode]`) and skip content carrying the other side's tag, so memories
-don't ping-pong between the two systems. This follows the same extension
-mechanism Codex itself uses to import Claude memories.
+After the next consolidation pass, durable facts from Claude's memories show up
+in this plugin's memory the same way OpenCode's own extractions do. Project-specific
+detail stays labeled by project; broadly useful preferences can land in the
+global summary.
+
+**Options** (all under `claude_import`):
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Turn the importer on. |
+| `claude_home` | `~/.claude` | Where Claude Code stores its data. Set this if you use a non-default location. |
+| `projects` | all projects | Optional allowlist of Claude project ids to import (see below). |
+
+**Limit to specific projects:**
+
+Claude names each project with an opaque id (a folder under
+`~/.claude/projects/`), not the path you work in. List those folder names:
+
+```json
+{
+  "plugin": [
+    [
+      "opencode-codex-memory@0.6.0",
+      {
+        "claude_import": {
+          "enabled": true,
+          "projects": ["-Users-you-Desktop-git-my-app"]
+        }
+      }
+    ]
+  ]
+}
+```
+
+Find the ids on your machine:
+
+```bash
+ls ~/.claude/projects
+```
+
+- Omit `projects` (or leave it empty) to import every Claude project the plugin
+  can place on disk.
+- Add or remove ids anytime while import is **on**. Dropping an id (or deleting
+  that project's memory in Claude) stops syncing it and removes the staging
+  copy on the next pass so consolidation can drop derived entries. Memory
+  already merged into the main store is not instantly deleted; the consolidator
+  cleans it up when it next runs.
+- Turning `enabled` off (see below) does **not** prune anything.
+
+**Turning it off**
+
+Setting `enabled` to `false` (or removing `claude_import`) only stops further
+import. Already merged memory stays in this plugin's store, and staging copies
+stay on disk (harmless while import is off).
+
+To drop the local staging copies too: turn import off first, then delete
+`extensions/external_agent_import/` under the plugin memory directory (see
+[Where your data lives](#where-your-data-lives)). Leave import off — if you turn
+it back on, the next pass will recreate them from Claude. After a deletion, the
+next consolidation can treat the missing files as a signal to drop entries that
+only came from that import.
+
+To stop importing *some* projects without turning the feature off: shrink
+`projects` (or delete that memory in Claude) and let the next pass run. That
+only affects the Claude import channel.
+
+**Notes**
+
+- Safe to combine with `codex_interop` (Codex sharing uses a separate channel).
+- If you also run another OpenCode plugin that *writes* Claude-style memory,
+  pick one writer — two systems updating the same long-term store will fight.
+- Check status anytime with `memory_inspect` (`claude_import:` section).
 
 ## Why one global memory?
 
@@ -360,6 +489,7 @@ It reports:
 - phase-2 status / last error / cooldown
 - last session-discovery outcome
 - effective options (after clamping) and config warnings
+- effective memory-agent health, including user overrides and required permissions
 - a short eligibility reminder (`min_rollout_idle_hours`, default **6h**)
 
 Common causes:

package/dist/src/agent-health.d.ts

@@ -0,0 +1,21 @@
+declare const AGENT_NAMES: readonly ["memorize", "memorize-extract"];
+type AgentName = (typeof AGENT_NAMES)[number];
+export interface AgentHealthEntry {
+    source: "shipped" | "user_override" | "missing";
+    healthy: boolean;
+    issues: string[];
+}
+export interface AgentHealthSnapshot {
+    observed: boolean;
+    generationEnabled: boolean | null;
+    agents: Record<AgentName, AgentHealthEntry>;
+}
+export declare function loadBundledAgentDefinitions(): Record<string, unknown>;
+/** Record the effective agent config after the plugin config hook runs. */
+export declare function recordAgentConfig(config: {
+    agent?: Record<string, unknown>;
+}, generationEnabled: boolean, shipped: Record<string, unknown>): void;
+export declare function getAgentHealth(): AgentHealthSnapshot;
+/** Test seam and boot boundary. */
+export declare function resetAgentHealth(): void;
+export {};

package/dist/src/agent-health.js

@@ -0,0 +1,133 @@
+import fs from "fs";
+import path from "path";
+import { memoryRoot } from "./paths.js";
+const AGENT_NAMES = ["memorize", "memorize-extract"];
+const REQUIRED_ALLOWS = {
+    memorize: ["read", "edit", "write", "glob", "grep"],
+    "memorize-extract": ["StructuredOutput"],
+};
+const SAFE_ALLOWS = {
+    memorize: new Set(["read", "edit", "write", "glob", "grep", "external_directory"]),
+    "memorize-extract": new Set(["StructuredOutput"]),
+};
+const initialEntry = () => ({ source: "missing", healthy: false, issues: ["config hook has not run"] });
+let snapshot = {
+    observed: false,
+    generationEnabled: null,
+    agents: {
+        memorize: initialEntry(),
+        "memorize-extract": initialEntry(),
+    },
+};
+export function loadBundledAgentDefinitions() {
+    const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
+    return JSON.parse(raw).agent ?? {};
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hasNonDenyAction(value) {
+    const rules = asRecord(value);
+    return rules ? Object.values(rules).some((action) => action !== "deny") : value !== "deny";
+}
+/** Structural compare — config reload re-parses shipped defs into new objects. */
+function definitionsEqual(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function permissionIssues(name, definition) {
+    const issues = [];
+    const record = asRecord(definition);
+    if (record?.mode !== "subagent")
+        issues.push("agent mode must be 'subagent'");
+    const permission = asRecord(record?.permission);
+    if (!permission) {
+        issues.push("missing permission map");
+        return issues;
+    }
+    const keys = Object.keys(permission);
+    if (keys[0] !== "*")
+        issues.push("permission wildcard '*' must be the first rule");
+    if (permission["*"] !== "deny")
+        issues.push("permission wildcard '*' must be 'deny'");
+    for (const toolName of REQUIRED_ALLOWS[name]) {
+        if (permission[toolName] !== "allow") {
+            issues.push(`required permission '${toolName}: allow' is missing`);
+        }
+    }
+    for (const [toolName, value] of Object.entries(permission)) {
+        if (toolName === "*")
+            continue;
+        if (!SAFE_ALLOWS[name].has(toolName)) {
+            if (hasNonDenyAction(value))
+                issues.push(`unexpected permission '${toolName}' must be denied`);
+        }
+    }
+    if (name === "memorize") {
+        const external = asRecord(permission.external_directory);
+        const expectedPath = path.join(memoryRoot(), "*");
+        if (external?.[expectedPath] !== "allow") {
+            issues.push(`consolidator must allow external_directory '${expectedPath}'`);
+        }
+        if (external) {
+            for (const [grantedPath, action] of Object.entries(external)) {
+                if (grantedPath === expectedPath)
+                    continue;
+                if (hasNonDenyAction(action)) {
+                    issues.push(`consolidator must deny extra external_directory '${grantedPath}'`);
+                }
+            }
+        }
+    }
+    else if (permission.external_directory !== undefined) {
+        issues.push("extractor must not have external_directory access");
+    }
+    return issues;
+}
+function inspectAgent(name, definition, source) {
+    const issues = permissionIssues(name, definition);
+    return { source, healthy: issues.length === 0, issues };
+}
+/** Record the effective agent config after the plugin config hook runs. */
+export function recordAgentConfig(config, generationEnabled, shipped) {
+    const configured = asRecord(config.agent);
+    const agents = {};
+    for (const name of AGENT_NAMES) {
+        const definition = configured?.[name];
+        const source = definition === undefined
+            ? "missing"
+            : definitionsEqual(shipped[name], definition)
+                ? "shipped"
+                : "user_override";
+        agents[name] = inspectAgent(name, definition, source);
+        if (!generationEnabled && definition === undefined) {
+            agents[name] = { source: "missing", healthy: true, issues: ["generation disabled; agent not injected"] };
+        }
+    }
+    snapshot = { observed: true, generationEnabled, agents };
+}
+export function getAgentHealth() {
+    return {
+        observed: snapshot.observed,
+        generationEnabled: snapshot.generationEnabled,
+        agents: {
+            memorize: { ...snapshot.agents.memorize, issues: [...snapshot.agents.memorize.issues] },
+            "memorize-extract": { ...snapshot.agents["memorize-extract"], issues: [...snapshot.agents["memorize-extract"].issues] },
+        },
+    };
+}
+/** Test seam and boot boundary. */
+export function resetAgentHealth() {
+    snapshot = {
+        observed: false,
+        generationEnabled: null,
+        agents: {
+            memorize: initialEntry(),
+            "memorize-extract": initialEntry(),
+        },
+    };
+}

package/dist/src/claude-import.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Claude Code memory import — port of codex's external-agent memory sync
+ * (codex-rs/external-agent-migration/src/memory.rs + memory_import.rs).
+ *
+ * One-way: reads Claude project memory markdown under
+ * `~/.claude/projects/<key>/memory/`, copies into
+ * `extensions/external_agent_import/resources/<key>/` with `scope.json`, and
+ * seeds `instructions.md` so phase-2 consolidation merges them. Never writes
+ * back to Claude. Never touches Claude session transcripts except to resolve
+ * a project cwd (newest *.jsonl with an absolute, existing cwd).
+ *
+ * Codex selects projects via a migration UI; this plugin has no such surface.
+ * When enabled, continuous phase-2 sync imports every project that has a
+ * reliable cwd (optional `projects` allowlist). Default-off.
+ */
+export declare const EXTENSION_NAME = "external_agent_import";
+export interface ClaudeImportOptions {
+    /** When true, sync Claude project memories into the extension each phase 2. */
+    enabled: boolean;
+    /** Override Claude home (default: `~/.claude`). */
+    claude_home?: string;
+    /**
+     * Optional project-key allowlist (Claude's `projects/<key>` directory names).
+     * Omitted/empty = every project with a reliable cwd.
+     */
+    projects?: string[];
+}
+export interface ExternalMemoryFile {
+    projectKey: string;
+    projectCwd: string | null;
+    sourcePath: string;
+    relativePath: string;
+}
+export interface ClaudeImportSyncResult {
+    changed: boolean;
+    synchronizedProjects: string[];
+    skippedNoCwd: string[];
+    failures: Array<{
+        projectKey: string;
+        message: string;
+    }>;
+}
+export declare function resolveClaudeHome(opts: ClaudeImportOptions): string;
+/**
+ * Resolve project cwd from Claude session jsonl under the project root.
+ * Mirrors codex project_cwd_from_sessions: newest *.jsonl first, first absolute
+ * cwd that canonicalizes to an existing directory wins.
+ */
+export declare function projectCwdFromSessions(projectRoot: string): string | null;
+/** Discover every Markdown file under each Claude project memory directory. */
+export declare function discoverExternalMemoryFiles(claudeHome: string): ExternalMemoryFile[];
+/** Owned = resource dirs that carry a regular scope.json (codex owned_project_keys). */
+export declare function ownedProjectKeys(): string[];
+/**
+ * Sync Claude project memories into `extensions/external_agent_import/`.
+ * Call inside a claimed phase-2 job after baseline, before diff capture.
+ * Unreachable Claude home → no-op (never a deletion signal).
+ */
+export declare function syncClaudeImport(opts: ClaudeImportOptions): ClaudeImportSyncResult;
+/** Inspect helpers: imported project keys + instruction mtime. */
+export declare function claudeImportStatus(): {
+    extensionPresent: boolean;
+    projects: string[];
+    instructionsMtimeMs: number | null;
+};