@mathew-cf/opencode-memory 0.3.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Persistent cross-session memory for [OpenCode](https://opencode.ai).
 
-This plugin gives the agent a durable knowledge base rooted at `~/opencode-memory/` — a git-tracked tree of markdown notes — plus read access to its own past sessions. A hybrid keyword + semantic search layer surfaces relevant notes before work starts, and a guard hook nudges the agent to save reusable discoveries as it goes.
+A durable knowledge base rooted at `~/opencode-memory/` — a git-tracked tree of markdown notes — paired with a hybrid keyword + semantic search layer. The OpenCode plugin provides tools, hooks, auto-applied config, and a bundled skill.
 
 ## Why
 
@@ -13,29 +13,31 @@ LLM agents forget everything between sessions. That means rediscovering the same
 | Category           | Additions                                                                 |
 | ------------------ | ------------------------------------------------------------------------- |
 | **Memory tools**   | `memory_search`, `memory_list`, `memory_save`, `memory_access`, `memory_setup` |
-| **Session tools**  | `session_search`, `session_read`, `session_list`                          |
-| **Hooks**          | Search-first nudge at 8 tool calls; discovery nudge on subagent outputs; retrospective reminder at compaction time |
-| **Skill**          | `opencode-memory` (auto-registered via the `skills.paths` config)         |
-| **Agent prompts**  | Built-in subagents (`general`, `explore`, `research`, `review`, `investigator`) get a memory-aware prompt prepended non-destructively |
+| **Session tools**  | `session_search`, `session_read`, `session_list` (OpenCode only — read OpenCode's SQLite history) |
+| **Hooks**          | Search-first nudge at 8 tool calls; discovery nudge on subagent outputs; retrospective reminder at compaction time (OpenCode only) |
+| **Skill**          | `opencode-memory` — auto-registered in OpenCode, dropped at `~/.agents/skills/opencode-memory` for Zed & Pi |
+| **Agent prompts**  | Built-in subagents (`general`, `explore`, `research`, `review`, `investigator`) get a memory-aware prompt prepended non-destructively (OpenCode only) |
 
 ## Installation
 
+### OpenCode
+
 ```jsonc
 // opencode.jsonc
 {
-  "plugin": ["@mathew-cf/opencode-memory@0.3.1"]
+  "plugin": ["@mathew-cf/opencode-memory@1.0.0"]
 }
 ```
 
-Then bootstrap the memory directory + embedding model:
+Then bootstrap the memory directory + embedding model + skill:
 
 ```bash
 bunx @mathew-cf/opencode-memory init
 ```
 
-This creates `~/opencode-memory/` (git repo, 7 category subdirs) and downloads the ~90MB embedding model. Idempotent — safe to re-run. Pass `--skip-model` to defer the download.
+This creates `~/opencode-memory/` (git repo, 7 category subdirs), downloads the ~90MB embedding model, and symlinks the bundled skill into `~/.agents/skills/opencode-memory` (where Zed and Pi look). Idempotent — safe to re-run. Pass `--skip-model` to defer the download, `--skip-skills` to skip the symlink.
 
-The plugin auto-registers:
+The plugin also auto-registers (OpenCode only):
 
 - its bundled skill under `config.skills.paths`
 - edit + external-directory permissions for `~/opencode-memory/**`
@@ -68,7 +70,7 @@ If either dependency fails to install (unusual — usually indicates an unsuppor
 bunx @mathew-cf/opencode-memory init
 ```
 
-Creates `~/opencode-memory/` (or `$MEMORY_DIR`), runs `git init`, scaffolds the 7 advisory category subdirs (`preferences/`, `repos/`, `technical/`, `people/`, `workflows/`, `snippets/`, `notes/`), and pre-caches the embedding model for semantic search.
+Creates `~/opencode-memory/` (or `$OPENCODE_MEMORY_DIR`), runs `git init`, scaffolds the 7 advisory category subdirs (`preferences/`, `repos/`, `technical/`, `people/`, `workflows/`, `snippets/`, `notes/`), and pre-caches the embedding model for semantic search.
 
 Subcommands:
 

package/dist/cli.d.ts

@@ -38,6 +38,18 @@
 interface InitOptions {
     /** Skip the rag download step. Useful in CI or for offline first-runs. */
     skipModel?: boolean;
+    /**
+     * Skip installing the bundled skill into `~/.agents/skills/`. By
+     * default `init` symlinks the skill there so Zed (`crates/agent_skills`)
+     * and Pi (`packages/coding-agent/docs/skills.md`) — both of which
+     * auto-discover that path — pick the skill up on next launch.
+     */
+    skipSkills?: boolean;
+    /**
+     * Override the directory where `installSkill` drops the symlink.
+     * Defaults to `~/.agents/skills`. Test-only escape hatch.
+     */
+    skillLinkDir?: string;
     /** Suppress success lines (errors still print). For embedding in scripts. */
     quiet?: boolean;
 }
@@ -55,7 +67,58 @@ export interface InitResult {
     modelDownloadAttempted: boolean;
     /** Whatever rag download printed, if it ran. */
     modelDownloadOutput?: string;
+    /**
+     * Outcome of the optional skill-symlink step. `null` when
+     * `skipSkills` was set. Otherwise see `SkillInstallResult` for the
+     * three valid resting states.
+     */
+    skillInstall: SkillInstallResult | null;
 }
+/**
+ * Result of installing the bundled `opencode-memory` skill into
+ * `~/.agents/skills/`. Captures the three valid resting states:
+ *  - `"created"`: a fresh symlink was placed at the target path
+ *  - `"already-installed"`: the target was already a symlink to our skill dir
+ *  - `"skipped-existing"`: a non-matching file/dir/symlink was already there
+ *    (we never overwrite — user-owned content wins)
+ *  - `"unavailable"`: the bundled skill dir wasn't resolvable on disk
+ *    (unusual; usually means the package layout was tampered with)
+ */
+export interface SkillInstallResult {
+    status: "created" | "already-installed" | "skipped-existing" | "unavailable";
+    /** Absolute path of the link we attempted to create. */
+    linkPath: string;
+    /** Absolute path the link points at (or would point at). */
+    targetPath: string;
+}
+/**
+ * Locate the bundled skills directory next to this file's package root.
+ *
+ * In src layout: `src/cli.ts` → `<repo>/skills`.
+ * In dist layout: `dist/cli.js` → `<pkg>/skills` (the `skills` folder
+ * is shipped in the npm package via `package.json` `files`).
+ *
+ * Exported so tests can monkey-patch the lookup if needed.
+ */
+export declare function resolveBundledSkillsDir(): string | undefined;
+/**
+ * Install (idempotent) the bundled `opencode-memory` skill into
+ * `~/.agents/skills/opencode-memory` — the directory Zed and Pi both
+ * auto-discover. Never overwrites a non-matching entry already at the
+ * target; users who manually placed something there keep ownership.
+ *
+ * Implementation: symlink rather than copy. Symlinks let plugin upgrades
+ * (`bun add @mathew-cf/opencode-memory@latest`) pick up new skill content
+ * without re-running `init`. The link points at the bundled skill
+ * directory inside the installed package.
+ *
+ * `linkDir` defaults to `~/.agents/skills` but is parameterised so tests
+ * can target a temp directory.
+ */
+export declare function installSkill(options: {
+    bundledSkillsDir: string | undefined;
+    linkDir?: string;
+}): Promise<SkillInstallResult>;
 /**
  * Pure-ish init: takes an explicit memoryDir so tests can target a temp
  * path. The CLI wrapper passes `resolveMemoryDir()`.
@@ -69,10 +132,35 @@ export declare function usage(): string;
  * Parse argv tail into a simple options bag. Exported for tests.
  * Recognised flags:
  *   --skip-model | -s    InitOptions.skipModel = true
+ *   --skip-skills        InitOptions.skipSkills = true
  *   --quiet | -q         InitOptions.quiet = true
  */
 export declare function parseInitFlags(argv: string[]): InitOptions;
-/** CLI dispatcher. Exported so tests can drive it without exec(). */
-export declare function dispatch(argv: string[]): Promise<number>;
+/**
+ * Writer functions for `dispatch`. Each receives a chunk of text exactly
+ * as it would be passed to `process.stdout.write` / `process.stderr.write`
+ * — including any trailing newlines. Callers must include their own
+ * newlines so passing `process.stdout.write.bind(process.stdout)` reads
+ * naturally.
+ *
+ * Exists primarily so tests can silence the CLI output without
+ * monkey-patching `process.stdout`, but the same shape lets embedders
+ * (e.g. a wrapping daemon) capture or redirect output cleanly.
+ */
+export interface DispatchIO {
+    /** Defaults to `process.stdout.write` bound to stdout. */
+    out?: (chunk: string) => void;
+    /** Defaults to `process.stderr.write` bound to stderr. */
+    err?: (chunk: string) => void;
+}
+/**
+ * CLI dispatcher. Exported so tests can drive it without exec().
+ *
+ * Output is routed through the optional `io.out` / `io.err` writers so
+ * tests (and any embedder) can capture or silence the chatter without
+ * having to monkey-patch global stdio. Defaults preserve the standalone
+ * bin behaviour exactly.
+ */
+export declare function dispatch(argv: string[], io?: DispatchIO): Promise<number>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAUH,UAAU,WAAW;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,yCAAyC;IACzC,sBAAsB,EAAE,OAAO,CAAC;IAChC,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,WAAgB,EACzB,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAgD,GACrE,OAAO,CAAC,UAAU,CAAC,CAuDrB;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAiB9B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAO1D;AAED,qEAAqE;AACrE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiC9D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAaH,UAAU,WAAW;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,yCAAyC;IACzC,sBAAsB,EAAE,OAAO,CAAC;IAChC,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,aAAa,CAAC;IAC7E,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAc5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE;IAC1C,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8C9B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,WAAgB,EACzB,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAgD,GACrE,OAAO,CAAC,UAAU,CAAC,CAkFrB;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAyB9B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAQ1D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAsCnF"}