hermes-plugin-qdrant-memory 0.2.1__tar.gz → 0.3.0__tar.gz

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/MANIFEST.in

@@ -4,3 +4,6 @@ prune assets
 
 # The text demo script is small and ships with the source distribution.
 include scripts/demo.sh
+include docs/local-embedding.md
+include requirements.txt requirements-local.txt
+recursive-include tests *.py

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-plugin-qdrant-memory
-Version: 0.2.1
+Version: 0.3.0
 Summary: Durable Qdrant memory for Hermes, standalone CLI and local MCP
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/cnkang/hermes-plugin-qdrant-memory
@@ -16,7 +16,9 @@ Requires-Dist: qdrant-client<2,>=1.15
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: portalocker<4,>=3.2
 Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.30; extra == "mcp"
+Requires-Dist: mcp<3,>=1.30; extra == "mcp"
+Provides-Extra: local
+Requires-Dist: fastembed==0.9.0; extra == "local"
 Dynamic: license-file
 
 # Qdrant Memory for Hermes
@@ -28,14 +30,20 @@ Dynamic: license-file
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-> **Runtime 0.2.1** provides the standalone CLI/MCP and fixes explicit writes of
-> distinct, highly similar texts. MCP distribution 0.1.1 pins Runtime 0.2.1.
+> **Runtime 0.3.0** adds optional offline CPU embedding and trusted setup
+> commands to the standalone CLI/MCP. It supports MCP Python SDK 1.x and 2.x.
+> Explicit writes retain canonical-text deduplication without an LLM.
+> MCP distribution 0.1.3 pins Runtime 0.2.2. The Runtime 0.3.0 update follows
+> in the MCP repository.
 > The Hermes Plugin Catalog has its own reviewed immutable pin. A PyPI release
 > does not upgrade it. One writer per destination remains required.
-> See [release notes](docs/releases/0.2.1.md) and [validation](docs/validation.md).
+> See [release notes](docs/releases/0.3.0.md) and [validation](docs/validation.md).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
+New in 0.3.0: [optional CPU embedding and guided setup](docs/local-embedding.md)
+adds explicit provider selection without changing Ollama or cloud configurations.
+
 Native long-term memory plugin for Hermes Agent, implemented as a `MemoryProvider`.
 Hermes performs extraction
 through its trusted `ctx.llm` facade. Qdrant stores named dense vectors and schema-v1
@@ -47,7 +55,7 @@ as a community-maintained plugin.
 ## How it works
 
 For non-Hermes users, install in a private Python 3.11+
-environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.2.1'` (omit `[mcp]`
+environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.3.0'` (omit `[mcp]`
 for CLI only). `qdrant-memory` is the CLI and `mcp` is its server subcommand.
 Standalone does not require Hermes. See [setup and quick start](docs/standalone.md).
 MCP-focused agents may instead use the [metadata-only distribution](https://github.com/cnkang/qdrant-memory-mcp).
@@ -106,8 +114,8 @@ The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ![Terminal recording: install the plugin, store a preference, and recall it in a new session](https://raw.githubusercontent.com/cnkang/hermes-plugin-qdrant-memory/main/assets/demo.gif)
 
-The recording shows the full flow on a clean profile. It installs from the
-official Hermes Plugin Catalog, teaches a preference, and waits for the
+The recording shows the full flow on a clean profile. It installs the
+verified pinned Runtime source, teaches a preference, and waits for the
 background extraction. Then it recalls the preference in a new session and
 cleans up the demo scope. All steps
 run in embedded mode. `scripts/demo.sh` reproduces the same walkthrough with
@@ -140,9 +148,28 @@ The install resolves the catalog's reviewed commit and prints the entry's declar
 tools, requirements and known issues before it clones anything.
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
 
-**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.3.0 source through the Hermes CLI.**
+
+This immutable source revision includes the optional CPU embedding and guided
+setup. It does not depend on a PyPI release or a catalog update.
+
+```bash
+export HERMES_HOME="/absolute/path/to/your/hermes-profile"
+ollama pull qwen3-embedding:4b
+# Start Ollama if it is not running. Keep its service available.
+hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
+  --ref 7c9e52d816b4f8e8109dbef2797f573b93e0d604   # verified Runtime 0.3.0 source
+hermes plugins enable qdrant-memory
+hermes memory setup
+hermes config set memory.provider qdrant-memory
+hermes qdrant-memory init
+```
+
+**Previous verified source: install Runtime 0.2.2 through the Hermes CLI.**
 
-This immutable source revision includes the explicit-write fix. It does not
+This older immutable source revision supports MCP SDK 1.x/2.x and includes the
+explicit-write fix, but it predates the optional CPU embedding and guided setup.
+For the current release use Runtime 0.3.0 above. It does not
 depend on a PyPI release or a catalog update.
 
 ```bash
@@ -150,7 +177,7 @@ export HERMES_HOME="/absolute/path/to/your/hermes-profile"
 ollama pull qwen3-embedding:4b
 # Start Ollama if it is not running. Keep its service available.
 hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
-  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
+  --ref c85d2bce788b117dddd854bb124971f7de8e564c   # verified Runtime 0.2.2 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -167,7 +194,7 @@ environment. Omit `--ref` to track `main`, the development line.
 **Historical release: clone a published tag manually.**
 
 The v0.1.0 tag below predates the standalone interfaces and the explicit-write
-fix. Use the pinned source above for Runtime 0.2.1.
+fix. Use the pinned source above for Runtime 0.3.0.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"

hermes_plugin_qdrant_memory-0.2.1/hermes_plugin_qdrant_memory.egg-info/PKG-INFO → hermes_plugin_qdrant_memory-0.3.0/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: hermes-plugin-qdrant-memory
-Version: 0.2.1
-Summary: Durable Qdrant memory for Hermes, standalone CLI and local MCP
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/cnkang/hermes-plugin-qdrant-memory
-Project-URL: Repository, https://github.com/cnkang/hermes-plugin-qdrant-memory
-Project-URL: Issues, https://github.com/cnkang/hermes-plugin-qdrant-memory/issues
-Project-URL: Changelog, https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/CHANGELOG.md
-Project-URL: MCP, https://github.com/cnkang/qdrant-memory-mcp
-Project-URL: Skill, https://github.com/cnkang/skills/tree/main/qdrant-memory
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: qdrant-client<2,>=1.15
-Requires-Dist: httpx<1,>=0.28
-Requires-Dist: portalocker<4,>=3.2
-Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.30; extra == "mcp"
-Dynamic: license-file
-
 # Qdrant Memory for Hermes
 
 [![CI](https://github.com/cnkang/hermes-plugin-qdrant-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/cnkang/hermes-plugin-qdrant-memory/actions/workflows/ci.yml)
@@ -28,14 +7,20 @@ Dynamic: license-file
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-> **Runtime 0.2.1** provides the standalone CLI/MCP and fixes explicit writes of
-> distinct, highly similar texts. MCP distribution 0.1.1 pins Runtime 0.2.1.
+> **Runtime 0.3.0** adds optional offline CPU embedding and trusted setup
+> commands to the standalone CLI/MCP. It supports MCP Python SDK 1.x and 2.x.
+> Explicit writes retain canonical-text deduplication without an LLM.
+> MCP distribution 0.1.3 pins Runtime 0.2.2. The Runtime 0.3.0 update follows
+> in the MCP repository.
 > The Hermes Plugin Catalog has its own reviewed immutable pin. A PyPI release
 > does not upgrade it. One writer per destination remains required.
-> See [release notes](docs/releases/0.2.1.md) and [validation](docs/validation.md).
+> See [release notes](docs/releases/0.3.0.md) and [validation](docs/validation.md).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
+New in 0.3.0: [optional CPU embedding and guided setup](docs/local-embedding.md)
+adds explicit provider selection without changing Ollama or cloud configurations.
+
 Native long-term memory plugin for Hermes Agent, implemented as a `MemoryProvider`.
 Hermes performs extraction
 through its trusted `ctx.llm` facade. Qdrant stores named dense vectors and schema-v1
@@ -47,7 +32,7 @@ as a community-maintained plugin.
 ## How it works
 
 For non-Hermes users, install in a private Python 3.11+
-environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.2.1'` (omit `[mcp]`
+environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.3.0'` (omit `[mcp]`
 for CLI only). `qdrant-memory` is the CLI and `mcp` is its server subcommand.
 Standalone does not require Hermes. See [setup and quick start](docs/standalone.md).
 MCP-focused agents may instead use the [metadata-only distribution](https://github.com/cnkang/qdrant-memory-mcp).
@@ -106,8 +91,8 @@ The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ![Terminal recording: install the plugin, store a preference, and recall it in a new session](https://raw.githubusercontent.com/cnkang/hermes-plugin-qdrant-memory/main/assets/demo.gif)
 
-The recording shows the full flow on a clean profile. It installs from the
-official Hermes Plugin Catalog, teaches a preference, and waits for the
+The recording shows the full flow on a clean profile. It installs the
+verified pinned Runtime source, teaches a preference, and waits for the
 background extraction. Then it recalls the preference in a new session and
 cleans up the demo scope. All steps
 run in embedded mode. `scripts/demo.sh` reproduces the same walkthrough with
@@ -140,9 +125,28 @@ The install resolves the catalog's reviewed commit and prints the entry's declar
 tools, requirements and known issues before it clones anything.
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
 
-**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.3.0 source through the Hermes CLI.**
+
+This immutable source revision includes the optional CPU embedding and guided
+setup. It does not depend on a PyPI release or a catalog update.
+
+```bash
+export HERMES_HOME="/absolute/path/to/your/hermes-profile"
+ollama pull qwen3-embedding:4b
+# Start Ollama if it is not running. Keep its service available.
+hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
+  --ref 7c9e52d816b4f8e8109dbef2797f573b93e0d604   # verified Runtime 0.3.0 source
+hermes plugins enable qdrant-memory
+hermes memory setup
+hermes config set memory.provider qdrant-memory
+hermes qdrant-memory init
+```
+
+**Previous verified source: install Runtime 0.2.2 through the Hermes CLI.**
 
-This immutable source revision includes the explicit-write fix. It does not
+This older immutable source revision supports MCP SDK 1.x/2.x and includes the
+explicit-write fix, but it predates the optional CPU embedding and guided setup.
+For the current release use Runtime 0.3.0 above. It does not
 depend on a PyPI release or a catalog update.
 
 ```bash
@@ -150,7 +154,7 @@ export HERMES_HOME="/absolute/path/to/your/hermes-profile"
 ollama pull qwen3-embedding:4b
 # Start Ollama if it is not running. Keep its service available.
 hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
-  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
+  --ref c85d2bce788b117dddd854bb124971f7de8e564c   # verified Runtime 0.2.2 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -167,7 +171,7 @@ environment. Omit `--ref` to track `main`, the development line.
 **Historical release: clone a published tag manually.**
 
 The v0.1.0 tag below predates the standalone interfaces and the explicit-write
-fix. Use the pinned source above for Runtime 0.2.1.
+fix. Use the pinned source above for Runtime 0.3.0.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"

hermes_plugin_qdrant_memory-0.3.0/docs/local-embedding.md

@@ -0,0 +1,152 @@
+# Optional local CPU embedding and guided setup
+
+These commands ship with Runtime 0.3.0. Published Runtime 0.2.2 and MCP
+distribution 0.1.3 predate them. Those packages keep their existing
+configuration workflow.
+
+## Choose your embedding provider
+
+The existing default remains Ollama. CPU embedding is optional and is never
+selected because Ollama or a cloud service happens to be unavailable. Existing
+profiles, models, fingerprints and collections are not changed by installation.
+
+| Choice | Requirements | Model download by this Runtime |
+| --- | --- | --- |
+| Ollama | Running service and installed embedding model | None |
+| OpenAI-compatible | Endpoint, model, dimensions and any required key | None |
+| FastEmbed CPU | Optional `local` extra and explicitly prepared model cache | About 252 MB for the pinned model/tokenizer files |
+
+The CPU model is multilingual MiniLM-L12-v2, 384 dimensions, using the
+[Qdrant ONNX artifacts](https://huggingface.co/Qdrant/paraphrase-multilingual-MiniLM-L12-v2-onnx-Q)
+and [FastEmbed](https://qdrant.github.io/fastembed/). The model is listed as
+Apache-2.0. Files are pinned to an immutable model revision and checked against
+exact sizes and SHA-256 values. Dependencies and installed environments require
+additional disk space. No remote Python model code is downloaded or executed.
+
+## Set up a new private profile without editing JSON
+
+For a reviewed source checkout, install the desired extras into a virtual
+environment. The `mcp` extra is needed for MCP, while `local` is needed only for
+CPU embedding:
+
+```sh
+python -m pip install '.[mcp,local]'
+```
+
+For a published package, install the same extras with the release version:
+
+```sh
+python -m pip install 'hermes-plugin-qdrant-memory[mcp,local]==0.3.0'
+```
+
+Choose **one** setup command and replace the profile path with a new absolute
+private directory. The command writes the configuration and initializes embedded
+Qdrant using the existing Runtime initialization, writer lease and validation.
+It does not install Python or prepare WorkBuddy's runtime environment.
+
+With an existing Ollama model (the `local` extra is unnecessary):
+
+```sh
+qdrant-memory setup --profile /absolute/new-profile --embedding-provider ollama --model qwen3-embedding:4b --dimensions 2560 --agent-id workbuddy
+```
+
+With an explicitly chosen CPU model:
+
+```sh
+qdrant-memory setup --profile /absolute/new-profile --embedding-provider fastembed --agent-id workbuddy
+```
+
+With an OpenAI-compatible embedding service:
+
+```sh
+qdrant-memory setup --profile /absolute/new-profile --embedding-provider openai-compatible --base-url https://embedding.example.com/v1 --model YOUR_MODEL --dimensions YOUR_DIMENSIONS --agent-id workbuddy
+```
+
+Replace the example endpoint/model/dimensions with the service's actual values.
+Provide `EMBEDDING_API_KEY` through a private process environment or a secret
+manager. Do not pass its value as a command argument. To use a different variable
+name, supply `--embedding-api-key-env VARIABLE_NAME`.
+
+Use a different profile and `--agent-id` for each client. `--user-id` defaults to
+`local-user`. Self-hosted/Cloud Qdrant storage continues to use the existing
+[configuration workflow](configuration.md); this setup command creates only a
+new embedded destination. A remote embedding choice is distinct from remote
+Qdrant storage.
+
+Once setup succeeds, configure the client's stdio command as `qdrant-memory`
+(or the installed `qdrant-memory-mcp` alias), with arguments:
+
+```text
+--home /absolute/new-profile mcp
+```
+
+The MCP tool catalogue remains search, add, update and delete. Model downloads
+and profile creation are trusted CLI operations, not conversational tools.
+WorkBuddy needs the launcher executable on its PATH or its absolute path.
+This source feature alone does not establish marketplace one-click installation.
+
+## Prepare the CPU model separately
+
+Installers can download the model before attempting MCP connection:
+
+```sh
+qdrant-memory prepare-model
+```
+
+`--cache-dir /absolute/model-cache` chooses a separate cache. Use the same cache
+with `setup --model-cache-dir /absolute/model-cache`, or set the profile's
+`embedding.model_cache_dir`. The default model-only cache follows platform
+conventions: macOS Library/Caches, Windows LOCALAPPDATA and Linux XDG_CACHE_HOME
+or `~/.cache`. It is separate from memory profiles, Qdrant data and the ledger.
+Managed cache/profile paths must be canonical absolute paths without symlinks
+or Windows reparse points, including intermediate directories.
+
+Preparation requires network access and may take several minutes. Start MCP
+after preparation and setup complete; do not place the download inside a
+30-second connection handshake. Normal provider startup verifies cached files
+and performs no downloads. Prepared CPU inference works offline and does not
+send memory/query text to an embedding service.
+
+Downloads use a provisioning lock and a private staging directory. The complete
+cache is published only after every file passes validation. Failed preparation
+can be retried with the same command. A corrupt completed cache is rejected and
+left untouched; it is not silently replaced. Select a new cache directory for
+explicit re-preparation, preserving the old files for diagnosis or recovery.
+
+## Safety, limits and recovery
+
+- Repeating the same setup request preserves memories. Setup refuses an unrelated
+  directory or a request changing the owned profile's configuration or scope.
+- A failed initialization can be retried with the same settings after fixing its
+  dependency/service problem. Existing data is never reset by setup.
+- CPU input is limited to **128 tokens including instruction prefixes**. Longer
+  input is rejected rather than silently truncated. Keep facts concise, or choose
+  an explicitly configured provider/model supporting longer inputs.
+- Cache location does not change CPU embedding identity. Model revision,
+  artifact hashes, preprocessing and the pinned FastEmbed version do.
+- Choosing CPU for a collection created with Ollama or another model is not a
+  migration. Existing incompatible collections fail compatibility checks.
+- `LocalModelNotPreparedError`: run explicit preparation with the correct cache.
+- `LocalModelIntegrityError`: do not bypass checks; explicitly prepare a new cache.
+- `LocalEmbeddingUnavailableError`: install the reviewed `local` extra.
+- `ManagedProfileConflictError`: retain the existing profile and choose a new
+  directory, or use the existing advanced configuration/maintenance workflow.
+
+Ordinary clients may still send recalled text to their chat model. Local embedding
+does not change the client's own data handling. No automatic conversation
+extraction, new network listener or cloud credential custody is introduced.
+
+## Validation boundary
+
+Real local CPU inference and offline official-MCP CRUD/restart tests are separate
+from package installation and real WorkBuddy GUI acceptance. The optional local
+embedding workflow tests native Linux x64, Windows x64 and macOS Apple Silicon
+with Python 3.11. macOS Intel is best-effort compatibility and is not a release
+gate or a formally supported CPU platform. A successful dependency resolution
+alone is not a platform support claim. ARM64 variants outside macOS require
+separate acceptance.
+
+The optional CPU dependency security snapshot is pinned with artifact hashes in
+`requirements-local.txt`, constrained by the existing base snapshot. CI scans
+both base and optional dependency sets. It does not make CPU packages mandatory
+for normal installations or replace platform/runtime installation acceptance.

hermes_plugin_qdrant_memory-0.2.1/README.md → hermes_plugin_qdrant_memory-0.3.0/hermes_plugin_qdrant_memory.egg-info/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: hermes-plugin-qdrant-memory
+Version: 0.3.0
+Summary: Durable Qdrant memory for Hermes, standalone CLI and local MCP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cnkang/hermes-plugin-qdrant-memory
+Project-URL: Repository, https://github.com/cnkang/hermes-plugin-qdrant-memory
+Project-URL: Issues, https://github.com/cnkang/hermes-plugin-qdrant-memory/issues
+Project-URL: Changelog, https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/CHANGELOG.md
+Project-URL: MCP, https://github.com/cnkang/qdrant-memory-mcp
+Project-URL: Skill, https://github.com/cnkang/skills/tree/main/qdrant-memory
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qdrant-client<2,>=1.15
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: portalocker<4,>=3.2
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.30; extra == "mcp"
+Provides-Extra: local
+Requires-Dist: fastembed==0.9.0; extra == "local"
+Dynamic: license-file
+
 # Qdrant Memory for Hermes
 
 [![CI](https://github.com/cnkang/hermes-plugin-qdrant-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/cnkang/hermes-plugin-qdrant-memory/actions/workflows/ci.yml)
@@ -7,14 +30,20 @@
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-> **Runtime 0.2.1** provides the standalone CLI/MCP and fixes explicit writes of
-> distinct, highly similar texts. MCP distribution 0.1.1 pins Runtime 0.2.1.
+> **Runtime 0.3.0** adds optional offline CPU embedding and trusted setup
+> commands to the standalone CLI/MCP. It supports MCP Python SDK 1.x and 2.x.
+> Explicit writes retain canonical-text deduplication without an LLM.
+> MCP distribution 0.1.3 pins Runtime 0.2.2. The Runtime 0.3.0 update follows
+> in the MCP repository.
 > The Hermes Plugin Catalog has its own reviewed immutable pin. A PyPI release
 > does not upgrade it. One writer per destination remains required.
-> See [release notes](docs/releases/0.2.1.md) and [validation](docs/validation.md).
+> See [release notes](docs/releases/0.3.0.md) and [validation](docs/validation.md).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
+New in 0.3.0: [optional CPU embedding and guided setup](docs/local-embedding.md)
+adds explicit provider selection without changing Ollama or cloud configurations.
+
 Native long-term memory plugin for Hermes Agent, implemented as a `MemoryProvider`.
 Hermes performs extraction
 through its trusted `ctx.llm` facade. Qdrant stores named dense vectors and schema-v1
@@ -26,7 +55,7 @@ as a community-maintained plugin.
 ## How it works
 
 For non-Hermes users, install in a private Python 3.11+
-environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.2.1'` (omit `[mcp]`
+environment: `pip install 'hermes-plugin-qdrant-memory[mcp]==0.3.0'` (omit `[mcp]`
 for CLI only). `qdrant-memory` is the CLI and `mcp` is its server subcommand.
 Standalone does not require Hermes. See [setup and quick start](docs/standalone.md).
 MCP-focused agents may instead use the [metadata-only distribution](https://github.com/cnkang/qdrant-memory-mcp).
@@ -85,8 +114,8 @@ The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ![Terminal recording: install the plugin, store a preference, and recall it in a new session](https://raw.githubusercontent.com/cnkang/hermes-plugin-qdrant-memory/main/assets/demo.gif)
 
-The recording shows the full flow on a clean profile. It installs from the
-official Hermes Plugin Catalog, teaches a preference, and waits for the
+The recording shows the full flow on a clean profile. It installs the
+verified pinned Runtime source, teaches a preference, and waits for the
 background extraction. Then it recalls the preference in a new session and
 cleans up the demo scope. All steps
 run in embedded mode. `scripts/demo.sh` reproduces the same walkthrough with
@@ -119,9 +148,28 @@ The install resolves the catalog's reviewed commit and prints the entry's declar
 tools, requirements and known issues before it clones anything.
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
 
-**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.3.0 source through the Hermes CLI.**
+
+This immutable source revision includes the optional CPU embedding and guided
+setup. It does not depend on a PyPI release or a catalog update.
+
+```bash
+export HERMES_HOME="/absolute/path/to/your/hermes-profile"
+ollama pull qwen3-embedding:4b
+# Start Ollama if it is not running. Keep its service available.
+hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
+  --ref 7c9e52d816b4f8e8109dbef2797f573b93e0d604   # verified Runtime 0.3.0 source
+hermes plugins enable qdrant-memory
+hermes memory setup
+hermes config set memory.provider qdrant-memory
+hermes qdrant-memory init
+```
+
+**Previous verified source: install Runtime 0.2.2 through the Hermes CLI.**
 
-This immutable source revision includes the explicit-write fix. It does not
+This older immutable source revision supports MCP SDK 1.x/2.x and includes the
+explicit-write fix, but it predates the optional CPU embedding and guided setup.
+For the current release use Runtime 0.3.0 above. It does not
 depend on a PyPI release or a catalog update.
 
 ```bash
@@ -129,7 +177,7 @@ export HERMES_HOME="/absolute/path/to/your/hermes-profile"
 ollama pull qwen3-embedding:4b
 # Start Ollama if it is not running. Keep its service available.
 hermes plugins install https://github.com/cnkang/hermes-plugin-qdrant-memory \
-  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
+  --ref c85d2bce788b117dddd854bb124971f7de8e564c   # verified Runtime 0.2.2 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -146,7 +194,7 @@ environment. Omit `--ref` to track `main`, the development line.
 **Historical release: clone a published tag manually.**
 
 The v0.1.0 tag below predates the standalone interfaces and the explicit-write
-fix. Use the pinned source above for Runtime 0.2.1.
+fix. Use the pinned source above for Runtime 0.3.0.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/hermes_plugin_qdrant_memory.egg-info/SOURCES.txt

@@ -2,6 +2,9 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
+requirements-local.txt
+requirements.txt
+docs/local-embedding.md
 hermes_plugin_qdrant_memory.egg-info/PKG-INFO
 hermes_plugin_qdrant_memory.egg-info/SOURCES.txt
 hermes_plugin_qdrant_memory.egg-info/dependency_links.txt
@@ -17,11 +20,15 @@ qdrant_memory/embedding.py
 qdrant_memory/extraction.py
 qdrant_memory/inventory.py
 qdrant_memory/ledger.py
+qdrant_memory/local_embedding.py
+qdrant_memory/local_model.py
+qdrant_memory/managed_setup.py
 qdrant_memory/mcp_server.py
 qdrant_memory/migration.py
 qdrant_memory/models.py
 qdrant_memory/ownership.py
 qdrant_memory/plugin.yaml
+qdrant_memory/private_paths.py
 qdrant_memory/progress.py
 qdrant_memory/provider.py
 qdrant_memory/qdrant_store.py
@@ -32,6 +39,9 @@ qdrant_memory/standalone.py
 qdrant_memory/tools.py
 qdrant_memory/version.py
 scripts/demo.sh
+tests/__init__.py
+tests/conftest.py
+tests/helpers.py
 tests/test_backend_contracts.py
 tests/test_bot_scope.py
 tests/test_bounded_recovery.py
@@ -43,9 +53,13 @@ tests/test_deletion_ordering.py
 tests/test_discovery_cli.py
 tests/test_explicit_dedupe.py
 tests/test_host_lifecycle.py
+tests/test_host_pins.py
 tests/test_input_validation.py
 tests/test_inventory_export.py
 tests/test_live_metrics.py
+tests/test_local_embedding.py
+tests/test_local_embedding_provider.py
+tests/test_local_model.py
 tests/test_maintenance.py
 tests/test_manifest_contract.py
 tests/test_migration.py
@@ -58,6 +72,7 @@ tests/test_provider.py
 tests/test_recovery_benchmark.py
 tests/test_recovery_evaluation.py
 tests/test_remote_qdrant.py
+tests/test_reset_inspection.py
 tests/test_reset_recovery.py
 tests/test_retention.py
 tests/test_review_regressions.py
@@ -65,4 +80,10 @@ tests/test_session_provenance.py
 tests/test_setup_contract.py
 tests/test_shutdown_contract.py
 tests/test_store_runtime.py
-tests/test_writer_ownership.py
+tests/test_writer_ownership.py
+tests/local_model/test_acceptance.py
+tests/standalone/__init__.py
+tests/standalone/test_explicit_writes.py
+tests/standalone/test_managed_setup.py
+tests/standalone/test_public_api.py
+tests/standalone/test_standalone.py

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/hermes_plugin_qdrant_memory.egg-info/requires.txt

@@ -2,5 +2,8 @@ qdrant-client<2,>=1.15
 httpx<1,>=0.28
 portalocker<4,>=3.2
 
+[local]
+fastembed==0.9.0
+
 [mcp]
-mcp<2,>=1.30
+mcp<3,>=1.30

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hermes-plugin-qdrant-memory"
-version = "0.2.1"
+version = "0.3.0"
 description = "Durable Qdrant memory for Hermes, standalone CLI and local MCP"
 readme = "README.md"
 license = "MIT"
@@ -16,7 +16,8 @@ dependencies = ["qdrant-client>=1.15,<2", "httpx>=0.28,<1", "portalocker>=3.2,<4
 qdrant-memory = "qdrant_memory.standalone:main"
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.30,<2"]
+mcp = ["mcp>=1.30,<3"]
+local = ["fastembed==0.9.0"]
 
 [project.urls]
 Homepage = "https://github.com/cnkang/hermes-plugin-qdrant-memory"
@@ -30,7 +31,7 @@ Skill = "https://github.com/cnkang/skills/tree/main/qdrant-memory"
 qdrant-memory = "qdrant_memory:register"
 
 [dependency-groups]
-test = ["pytest>=8,<10", "pytest-cov>=6,<8", "ruamel.yaml>=0.18.16,<0.20", "mcp>=1.30,<2"]
+test = ["pytest>=8,<10", "pytest-cov>=6,<8", "ruamel.yaml>=0.18.16,<0.20", "mcp>=1.30,<3"]
 
 [tool.setuptools.packages.find]
 include = ["qdrant_memory*"]

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/qdrant_memory/config.py

@@ -139,9 +139,14 @@ def validate_embedding(cfg):
     if cfg["embedding"]["mode"] == "inherit" and not cfg["embedding"].get("inherit_fallback"):
         raise ValueError("Embedding inheritance requires an explicit fallback")
     emb = embedding_config(cfg)
-    if emb["provider"] not in {"ollama", "openai-compatible"}:
+    if emb["provider"] not in {"ollama", "openai-compatible", "fastembed"}:
         raise ValueError("Unsupported embedding provider")
-    validate_url(emb["base_url"], api_key=emb.get("api_key"))
+    if emb["provider"] == "fastembed":
+        from .local_model import validate_local_config
+
+        validate_local_config(emb)
+    else:
+        validate_url(emb["base_url"], api_key=emb.get("api_key"))
     if emb["distance"] not in {"Cosine", "Dot", "Euclid"}:
         raise ValueError("Unsupported distance metric")
     return emb
@@ -272,7 +277,13 @@ def fingerprint(emb):
         "send_dimensions",
     )
     values = {k: emb.get(k) for k in keys}
-    if isinstance(values["base_url"], str):
+    if emb.get("provider") == "fastembed":
+        from .local_model import pipeline_identity
+
+        values.pop("base_url")
+        values.pop("send_dimensions")
+        values["local_pipeline"] = pipeline_identity()
+    if isinstance(values.get("base_url"), str):
         values["base_url"] = values["base_url"].rstrip("/")
     return hashlib.sha256(json.dumps(values, sort_keys=True).encode()).hexdigest()
 

{hermes_plugin_qdrant_memory-0.2.1 → hermes_plugin_qdrant_memory-0.3.0}/qdrant_memory/embedding.py

@@ -111,4 +111,9 @@ def build_embedder(ctx, cfg, *, secret_reader=None):
             ):
                 raise ValueError("Host embedding facade does not satisfy the plugin contract")
             return host
-    return HTTPEmbeddingProvider(embedding_config(cfg), secret_reader=secret_reader)
+    selected = embedding_config(cfg)
+    if selected["provider"] == "fastembed":
+        from .local_embedding import LocalEmbeddingProvider
+
+        return LocalEmbeddingProvider(selected)
+    return HTTPEmbeddingProvider(selected, secret_reader=secret_reader)