release: prepare native memory 0.6.0

Author: nguyenthdat

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "opencode-memory"
-version = "0.6.0-beta.2"
+version = "0.6.0"
 edition = "2024"
 license = "MIT"
 rust-version = "1.97"

Cargo.toml

@@ -24,7 +24,7 @@ Add the plugin to `opencode.json` or `opencode.jsonc`:
 
 ```json
 {
-  "plugin": ["@nguyenthdat/opencode-memory@0.6.0-beta.2"]
+  "plugin": ["@nguyenthdat/opencode-memory@0.6.0"]
 }
 ```
 
@@ -33,7 +33,7 @@ The package also includes an OpenCode TUI companion. Enable it in `tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["@nguyenthdat/opencode-memory@0.6.0-beta.2"]
+  "plugin": ["@nguyenthdat/opencode-memory@0.6.0"]
 }
 ```
 
@@ -86,6 +86,29 @@ The plugin automatically registers its packaged `rules/native-memory.md` as an O
 | `memory_status`          | Health-check the plugin and inspect backend, model, and schema status     |
 | `memory_doctor`          | Run shallow or deep integrity checks                                      |
 | `memory_purge`           | Confirm and delete the complete project store                             |
+| `memory_model_profiles`  | List stable, preview, and unsupported embedding model profiles            |
+| `memory_model_switch`    | Run a non-mutating model switch preflight                                 |
+
+### Embedding Profiles
+
+The daemon owns an immutable profile catalog. The current selectable default is
+`qwen3-text-4b-q4`, which preserves the existing Qwen3 4B GGUF configuration.
+The catalog also describes popular presets such as `qwen3-text-0.6b-q8`,
+`qwen3-text-8b-q4`, `bge-m3`, and `nomic-embed-text-v1.5`, plus experimental
+Qwen3-VL 2B/8B entries. Preview and multimodal entries are visible but not
+selectable until their artifact, runtime, quality, and memory gates pass.
+
+Use the safe phase-1 commands:
+
+```text
+/memory model profiles
+/memory model switch qwen3-text-0.6b-q8 --dry-run
+/memory model switch qwen3-vl-embedding-8b --dry-run
+```
+
+The current release performs preflight only. It never changes an existing
+project's model or mixes incompatible vectors. Durable collection-generation
+migration, cancellation, resume, and rollback are a later phase.
 
 The 15 stable taxonomy values are `task_attempt`, `tool_call`, `session_summary`, `architecture_fact`, `codebase_fact`, `user_fact`, `fix_pattern`, `code_template`, `tool_heuristic`, `code_style`, `library_pref`, `workflow_pref`, `decision`, `team_convention`, and `project_standard`.
 
@@ -137,6 +160,8 @@ Changing model identity or vector-affecting preprocessing requires rebuilding th
 | `OPENCODE_MEMORY_AUTO_CAPTURE`               | Evaluate compaction candidates through the capture gate; default `true`      |
 | `OPENCODE_MEMORY_AUTO_INDEX_DOCUMENTS`       | Incrementally index non-ignored project documents; default `true`            |
 | `OPENCODE_MEMORY_DOCUMENT_INDEX_DEBOUNCE_MS` | File-watcher re-index debounce; default `750`                                |
+| `OPENCODE_MEMORY_AUTO_OPTIMIZE`              | Coalesced zvec compaction after writes/index drift; default `true`           |
+| `OPENCODE_MEMORY_OPTIMIZE_DEBOUNCE_MS`       | Maintenance debounce; default `5000`                                         |
 | `OPENCODE_MEMORY_SHARED_SYNC`                | Synchronize `.opencode/memory/**/*.md`; default `true`                       |
 | `OPENCODE_MEMORY_FEEDBACK_TRACKING`          | Track retrieval feedback; default `true`                                     |
 | `OPENCODE_MEMORY_MIN_SCORE`                  | Default calibrated search threshold; default `0.42`                          |
@@ -170,6 +195,14 @@ Shared Markdown is treated as untrusted data: paths are contained under `.openco
 
 Automatic document indexing scans the project at startup and after debounced document watcher events. It respects `.gitignore`, `.ignore`, `.git/info/exclude`, global Git ignores, hidden directories, and the 32 MiB per-file limit; `.opencode/memory/` remains managed exclusively by repository-memory sync. A private derived manifest at `document-index.json` tracks source hashes and chunk ownership, so unchanged files skip extraction/embedding, changed files replace their previous chunks, deleted files are removed without tombstones, and a malformed file retains its last valid index. Set `OPENCODE_MEMORY_AUTO_INDEX_DOCUMENTS=false` to disable automatic synchronization, or call `memory_index_documents` for an explicit/forced run.
 
+Automatic maintenance coalesces index/shared-memory/capture writes and runs
+`optimize` after a short debounce when zvec index completeness drops below
+98% or pending journals are observed. `index_documents`, `sync_shared`, and
+`optimize` are deterministic maintenance operations; if their response is
+lost after dispatch, the plugin retries the same operation once and never
+replays arbitrary mutations. Disable this behavior with
+`OPENCODE_MEMORY_AUTO_OPTIMIZE=false`.
+
 ## Architecture
 
 ```text

README.md

@@ -3,8 +3,16 @@ fn main() {
         .compile_protos(&["schema/opencode/memory/v1/memory.proto"], &["schema"])
         .expect("compile Protobuf memory protocol schema");
 
+    prost_build::Config::new()
+        .compile_protos(
+            &["schema/opencode/memory/model/v1/model.proto"],
+            &["schema"],
+        )
+        .expect("compile Protobuf model protocol schema");
+
     let mut daemon = prost_build::Config::new();
     daemon.extern_path(".opencode.memory.v1", "crate::memory_proto");
+    daemon.extern_path(".opencode.memory.model.v1", "crate::model_proto");
     daemon
         .compile_protos(
             &["schema/opencode/memory/daemon/v1/daemon.proto"],
@@ -23,6 +31,7 @@ fn main() {
         _ => {}
     }
     println!("cargo:rerun-if-changed=schema/opencode/memory/v1/memory.proto");
+    println!("cargo:rerun-if-changed=schema/opencode/memory/model/v1/model.proto");
     println!("cargo:rerun-if-changed=schema/opencode/memory/daemon/v1/daemon.proto");
     println!("cargo:rerun-if-changed=build.rs");
 }

build.rs

@@ -0,0 +1,89 @@
+# Embedding Engine Phase 1
+
+Status: Implemented locally
+
+## Decision
+
+Pressure: embedding inference was serialized around complete project calls,
+including lexical work, zvec writes, ranking, and state fsync. Bulk shared-memory
+and document transactions also submitted one zvec upsert call per record. Model
+selection remained a set of raw environment fields without a discoverable,
+daemon-owned profile catalog.
+
+Decision: keep llama.cpp inference globally serialized, but move the lock to the
+actual query/passage embedding calls. Batch zvec upserts and shared-memory
+commits without weakening the durable pending journal. Add an immutable catalog
+of stable, preview, and unsupported profiles, and expose profile listing plus a
+non-mutating switch preflight.
+
+Language form: Rust value types and exhaustive Protobuf enum additions for the
+closed profile-control methods; one shared TypeScript model-control facade for
+the OpenCode tools.
+
+Ownership: the daemon owns profile support decisions and preflight. Project
+actors remain the only storage writers. `MemoryEngine` owns its collection and
+embedder, while the daemon registry injects the shared inference lock. The
+plugin never constructs model repository configurations.
+
+Alternatives: changing model environment variables or rebuilding `zvec/` in
+place was rejected because incompatible vectors could mix or make an existing
+project unreadable. A public mutating switch was deferred because collection
+generations, an active pointer, a durable switch journal, mutation freeze,
+resume, cancellation, and rollback are not implemented yet.
+
+Costs: profile metadata is duplicated from reviewed upstream model information
+until an artifact-lock file is introduced. Preview profiles are visible but not
+selectable. Actual model cutover remains a later generation-migration phase.
+
+## Invariants
+
+1. At most one llama.cpp embedding call runs at a time across project actors.
+2. Lexical search, ranking, zvec flush, and state fsync do not hold inference
+   capacity.
+3. One pending upsert batch produces one zvec upsert call and one flush.
+4. Shared-memory replacements are deleted only after successor writes commit.
+5. Profile listing and dry-run preflight do not initialize `MemoryEngine` or
+   load a model.
+6. Only `qwen3-text-4b-q4` is selectable in phase 1.
+7. Qwen3-VL profiles remain unsupported until runtime, artifact, quality,
+   portability, and memory gates pass.
+8. A non-dry-run switch is rejected before any project mutation.
+
+## Built-In Profiles
+
+| Profile                 | Support     | Runtime                        | Phase-1 behavior           |
+| ----------------------- | ----------- | ------------------------------ | -------------------------- |
+| `qwen3-text-4b-q4`      | Stable      | llama.cpp GGUF                 | Current/default profile    |
+| `qwen3-text-0.6b-q8`    | Preview     | llama.cpp GGUF                 | Visible, preflight blocked |
+| `qwen3-text-8b-q4`      | Preview     | llama.cpp GGUF                 | Visible, preflight blocked |
+| `bge-m3`                | Preview     | Unvalidated                    | Visible, unsupported       |
+| `nomic-embed-text-v1.5` | Preview     | Unvalidated                    | Visible, unsupported       |
+| `qwen3-vl-embedding-2b` | Unsupported | No packaged multimodal runtime | Visible, unsupported       |
+| `qwen3-vl-embedding-8b` | Unsupported | No packaged multimodal runtime | Visible, unsupported       |
+
+The Qwen GGUF presets include pinned repository revisions and LFS SHA-256
+digests. They remain non-selectable until retrieval-quality gates and the
+generation migration are implemented.
+
+The next phase adds legacy-root generation adaptation, managed generation
+manifests, an atomic active pointer, and generation-aware pending journals
+before any mutating switch command is enabled.
+
+## Protobuf Boundary
+
+The live memory wire contract remains in
+`schema/opencode/memory/v1/memory.proto`; its released `Method`, `Request`, and
+`Response` tags are unchanged. Model control is in
+`schema/opencode/memory/model/v1/model.proto` with typed request/response
+`oneof`s. `daemon.proto` adds new model branches without changing the existing
+memory branch. Memory and model requests are validated as exactly one domain at
+daemon admission, and the domain schema generation is incremented to `2` so an
+older daemon cannot silently ignore a model branch.
+
+The split follows the Protocol Buffers best-practice rules: new model messages
+use fresh field numbers, old memory model-method numbers are reserved, enums
+start with an `UNSPECIFIED` zero value, model operations use `oneof` rather than
+an open method/payload pair, and optional fields preserve presence for nullable
+profile metadata. The two domain files are intentionally grouped API surfaces
+for this two-file packaging boundary; storage state remains represented by Rust
+domain types and is not coupled to the RPC messages.

bun.lock

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenthdat/opencode-memory-darwin-arm64",
-  "version": "0.6.0-beta.2",
+  "version": "0.6.0",
   "description": "Shared native OpenCode memory daemon for macOS ARM64",
   "os": [
     "darwin"

docs/embedding-engine-phase1.md

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenthdat/opencode-memory-linux-arm64-gnu",
-  "version": "0.6.0-beta.2",
+  "version": "0.6.0",
   "description": "Shared native OpenCode memory daemon for Linux ARM64 glibc",
   "os": [
     "linux"

npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenthdat/opencode-memory-linux-x64-gnu",
-  "version": "0.6.0-beta.2",
+  "version": "0.6.0",
   "description": "Shared native OpenCode memory daemon for Linux x64 glibc",
   "os": [
     "linux"

npm/linux-arm64-gnu/package.json

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import type { CaptureResponse } from "./contracts.js";
+import {
+  captureWithOutcomeReconciliation,
+  type ReconciledCaptureResponse,
+} from "./capture-reconciliation.js";
+import { DaemonOutcomeUnknownError, type NativeMemoryRequester } from "./daemon-client.js";
+import type { MemoryMethod } from "./protocol.js";
+
+describe("automatic capture reconciliation", () => {
+  test("does not replay a capture that returned normally", async () => {
+    const response = storedResponse();
+    const native = captureRequester([response]);
+
+    const result = await captureWithOutcomeReconciliation(native, { candidate: "memory" });
+
+    expect(result).toEqual({ response, reconciled: false, storedOrDuplicate: true });
+    expect(native.calls).toBe(1);
+  });
+
+  test("replays once and treats duplicate as a committed first attempt", async () => {
+    const duplicate: CaptureResponse = {
+      decision: { outcome: "skip", reason: "duplicate" },
+    };
+    const native = captureRequester([
+      new DaemonOutcomeUnknownError("response lost", "call-1"),
+      duplicate,
+    ]);
+
+    const result = await captureWithOutcomeReconciliation(native, { candidate: "memory" });
+
+    expect(result).toEqual({ response: duplicate, reconciled: true, storedOrDuplicate: true });
+    expect(native.calls).toBe(2);
+  });
+
+  test("does not replay definite capture failures", async () => {
+    const failure = new Error("validation failed");
+    const native = captureRequester([failure]);
+
+    await expect(captureWithOutcomeReconciliation(native, {})).rejects.toThrow("validation failed");
+    expect(native.calls).toBe(1);
+  });
+});
+
+function captureRequester(
+  outcomes: Array<CaptureResponse | Error>,
+): NativeMemoryRequester & { calls: number } {
+  return {
+    calls: 0,
+    async request<T>(method: MemoryMethod): Promise<T> {
+      expect(method).toBe("capture");
+      const outcome = outcomes[this.calls++];
+      if (outcome instanceof Error) throw outcome;
+      if (!outcome) throw new Error("missing test outcome");
+      return outcome as T;
+    },
+  };
+}
+
+function storedResponse(): CaptureResponse {
+  return {
+    decision: { outcome: "accept" },
+    stored: {
+      id: "mem_1",
+      inserted: true,
+      content_hash: "hash",
+      updated_at_ms: 1,
+      scope: "project",
+    },
+  };
+}