feat(memory): add opt-in scoped memory tools

README.md

@@ -14,12 +14,56 @@ to the repository release.
 - Subagents: planner, code reviewer, and security reviewer.
 - Plugin tool: `toolkit_project_status`, implemented against OpenCode's V2 VCS
   API and exposed in the `toolkit` Code Mode namespace.
+- Optional memory tools, disabled by default. Session memory is isolated by
+  project and session; shared project memory requires a separate opt-in.
 - Project installer with JSONC-preserving plugin registration, file ownership
   hashes, collision checks, and protection for locally modified files.
 
 Provider/model selection remains the user's OpenCode configuration. The package
 does not enable hooks through a global install or configure credentials.
 
+## Optional memory
+
+Memory is off unless enabled in the consuming project's plugin options. To turn
+on session memory, convert the installer-added plugin string into an object
+entry, keeping its existing local package path:
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "./node_modules/@sargatxet/opencode-toolkit",
+      "options": {
+        "memory": {
+          "enabled": true,
+          "retentionDays": 30
+        }
+      }
+    }
+  ]
+}
+```
+
+If the project uses `.opencode/opencode.json`, retain the different relative
+path the installer registered (typically `../node_modules/...`). The toolkit
+does not automatically capture prompts, tool results, or session summaries.
+Use `toolkit_memory_save`, `toolkit_memory_list`, `toolkit_memory_get`, and
+`toolkit_memory_delete` explicitly. Retrieval and list previews are returned to
+the current model session as tool output. Memory content is stored through
+OpenCode's plugin storage; do not store credentials or secrets.
+
+Session scope is the default and is limited to the current project/session.
+Project-wide sharing remains disabled unless the options also contain
+`"project": true` inside `memory`. Project memories are shared by sessions and
+worktrees belonging to the same canonical OpenCode project. Retention defaults
+to 30 days and can be set from 1 to 3650 days. Expired records are not returned
+and are deleted when accessed; there is no background cleanup job. Delete
+individual records explicitly with `toolkit_memory_delete`.
+
+Uninstall preserves a plugin object entry because it may contain user options.
+If you enabled memory by converting the installer-added string to an object,
+remove that plugin entry from the project config yourself when uninstalling.
+
 ## Install the pre-release
 
 From the project where you want to use the toolkit, run:
@@ -93,6 +137,9 @@ the toolkit plugin entry should be removed. These install/uninstall checks need
 no model credentials. Plugin activation and tool execution were separately
 smoke-tested with OpenCode 2.0.24 and a local mock OpenAI-compatible endpoint.
 Provider-backed agent delegation and skill behavior remain unverified.
+Memory behavior is covered by deterministic storage-contract tests; persistence
+inside a running OpenCode profile and provider-backed learning flows are not yet
+verified.
 
 ## Safety boundaries