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

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

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: hermes-plugin-qdrant-memory
-Version: 0.2.0
+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
@@ -26,12 +28,11 @@ 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)
 
-> **v0.1.0 — limited technical preview.** Give Hermes Agent durable, private
-> long-term memory: your conversations become searchable memories in your own
-> Qdrant store, with recall, update and scoped deletion under your control.
-> The preview supports one writer per destination, with the documented
-> durability limits. See the [validation record](docs/validation.md) for the
-> current certification.
+> **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.
+> 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).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
@@ -45,6 +46,16 @@ 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]`
+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).
+Public releases: [Runtime on PyPI](https://pypi.org/project/hermes-plugin-qdrant-memory/)
+and [MCP distribution on PyPI](https://pypi.org/project/qdrant-memory-mcp/).
+For native Hermes use its official plugin installation mechanism below. Before
+an authorized upgrade, verify the same profile, collection and embedding pipeline.
+
 ```mermaid
 flowchart LR
     turn["Hermes turn"] --> admit["Provider callback"]
@@ -66,7 +77,7 @@ flowchart LR
 - A fully local setup works: embedded Qdrant and local Ollama keep the data
   on your machine.
 - Data locality follows the destination. Extraction uses the LLM configured
-  in Hermes, and embedding uses the configured embedding service; either can
+  in Hermes, and embedding uses the configured embedding service. Either can
   be remote. See [Data flow and privacy](#data-flow-and-privacy).
 - Not supported in this preview: multi-writer Server/Cloud, hybrid search and
   a web UI.
@@ -75,9 +86,9 @@ flowchart LR
 
 The plugin primarily provides Hermes Agent's durable memory integration. As an
 additional capability, its shared backend can serve other agents through the
-Runtime 0.2.0's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
-interface, without requiring Hermes. These interfaces support explicit scoped
-memory operations and maintenance/migration; automatic extraction and prefetch
+Runtime's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
+interface. Standalone use does not require Hermes. These interfaces support explicit scoped
+memory operations and maintenance/migration. Automatic extraction and prefetch
 remain Hermes lifecycle features. See [standalone setup](docs/standalone.md) for
 configuration and boundaries, and the agent-neutral
 [qdrant-memory skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)
@@ -85,19 +96,20 @@ for multi-agent installation and usage guidance.
 
 The optional MCP server exposes four scoped tools: `qdrant_memory_search`,
 `qdrant_memory_add`, `qdrant_memory_update` and `qdrant_memory_delete`. Compatible
-clients launch it as a local stdio process and discover/call those tools;
-maintenance and migration use the operator CLI. See the
+clients launch it as a local stdio process and discover/call those tools.
+Maintenance and migration use the operator CLI. See the
 [MCP capabilities and connection guide](docs/mcp.md) for setup, shared-memory
-boundaries and the verified agent matrix. This is a tested source preview;
-the published v0.1.0 plugin release does not include the MCP entrypoint.
+boundaries and the verified agent matrix. Runtime 0.2.0 published these interfaces.
+The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ## See it in action
 
 ![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: install from the
-official Hermes Plugin Catalog, teach a preference, wait for the background
-extraction, recall it in a new session, and clean up the demo scope. All steps
+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
+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
 the pinned release.
 
@@ -128,14 +140,17 @@ 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 pinned release through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+
+This immutable source revision includes the explicit-write fix. 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 5babd3e4b4c022aad38a2b6db82cbd5b601f1ef8   # v0.1.0 release commit
+  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -144,12 +159,15 @@ hermes qdrant-memory init
 
 For this version-locked form, `hermes plugins install` checks out the given ref, and
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
-`--ref` takes a full 40-character commit SHA; the
+`--ref` takes a full 40-character commit SHA. The
 [releases page](https://github.com/cnkang/hermes-plugin-qdrant-memory/releases)
 lists the release commits. Do not pip-install into a managed Hermes
 environment. Omit `--ref` to track `main`, the development line.
 
-**Alternative: clone the release tag manually.**
+**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.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"
@@ -178,7 +196,7 @@ import and registration. For development installs, see
 [development setup](docs/development.md).
 
 The release notes, supported Hermes/Python versions and the current
-limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md);
+limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md).
 `main` stays the development line.
 
 For local development, symlink the repository into a disposable profile:
@@ -223,7 +241,10 @@ mappings) stays in the local Hermes home. Back up that home together with your
 Qdrant data. Migration from Mem0 is one-way, and version 0.1 has no vector
 reuse or hybrid retrieval.
 
-Similarity is a candidate-selection signal, not proof that two facts are identical.
+Explicit add deduplicates only canonical text in the same scope and never calls
+an LLM. Different texts are saved regardless of similarity. Update replaces only
+the authorized exact ID. For automatic Hermes extraction,
+similarity is a candidate-selection signal, not proof that two facts are identical.
 `SAME` skips, `SUPERSEDES` updates, `CONFLICT` creates a linked record, and
 `UNRELATED` adds a record. Migration uses source IDs instead of semantic merging.
 
@@ -305,7 +326,7 @@ default profile scope uses an agent (`hermes`). Pass `--agent hermes` to
 target it, or `--all-agents` to delete every agent scope of the user. Without
 `--all-agents`, the result reports `other_agent_scopes` when other agent
 scopes still hold memories. A literal `*` is an ordinary agent id, not a
-wildcard. `--dry-run` previews the per-scope counts;
+wildcard. `--dry-run` previews the per-scope counts.
 `--confirm` authorizes deletion. An interrupted deletion fails closed: other
 commands and provider startup return `scope_delete_recovery_required` until
 `delete-all --confirm` resumes it. Deletion intents are versioned and explicit.
@@ -313,8 +334,8 @@ A pre-versioned intent cannot show whether `*` is a single agent or all agents,
 so the plugin refuses it (`scope_delete_legacy_intent`). Resolve it with
 `--resolve-legacy single_agent`, or with `--resolve-legacy all_agents` when the
 record's agent is `*` or absent. Turns admitted after the deletion can still
-add new memories; everything admitted before it — stored memories, prepared
-writes and unprocessed turn events — is removed or invalidated. `list`,
+add new memories. Everything admitted before it, including stored memories, prepared
+writes and unprocessed turn events, is removed or invalidated. `list`,
 `export` and `delete-all` do not require the embedding service.
 
 ## Data flow and privacy
@@ -325,10 +346,10 @@ carries and where it can go:
 | Component | Carries | Destination |
 | --- | --- | --- |
 | Chat / agent turns | Your conversation | The model configured for the Hermes session |
-| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model — with a cloud model, turn text reaches that cloud |
-| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction; runs only when similarity selects a review candidate |
+| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model. With a cloud model, turn text reaches that cloud |
+| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction. It runs only when similarity selects a review candidate |
 | Embeddings (`embedding`) | Memory and search text | Ollama by default, or your OpenAI-compatible endpoint |
-| Storage (`qdrant`) | Memory payloads and provenance; the ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
+| Storage (`qdrant`) | Memory payloads and provenance. The ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
 
 Three common deployments:
 
@@ -483,7 +504,7 @@ contains `memories` objects with `id`/`text`, and `queries` with `query`/`releva
 The default fixture now contains 24 labeled queries, including Chinese, English,
 mixed-language and hard-negative cases. The
 [original 12-query recording](docs/retrieval-baseline.json) is a historical
-synthetic regression baseline; rerun the current fixture for current measurements.
+synthetic regression baseline. Rerun the current fixture for current measurements.
 These fixtures do not establish production recall quality. See the [recovery benchmark](docs/recovery-benchmark.md)
 for a separate synthetic replay and retained-storage measurement.
 

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

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: hermes-plugin-qdrant-memory
-Version: 0.2.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
-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)
@@ -26,12 +7,11 @@ 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)
 
-> **v0.1.0 — limited technical preview.** Give Hermes Agent durable, private
-> long-term memory: your conversations become searchable memories in your own
-> Qdrant store, with recall, update and scoped deletion under your control.
-> The preview supports one writer per destination, with the documented
-> durability limits. See the [validation record](docs/validation.md) for the
-> current certification.
+> **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.
+> 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).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
@@ -45,6 +25,16 @@ 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]`
+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).
+Public releases: [Runtime on PyPI](https://pypi.org/project/hermes-plugin-qdrant-memory/)
+and [MCP distribution on PyPI](https://pypi.org/project/qdrant-memory-mcp/).
+For native Hermes use its official plugin installation mechanism below. Before
+an authorized upgrade, verify the same profile, collection and embedding pipeline.
+
 ```mermaid
 flowchart LR
     turn["Hermes turn"] --> admit["Provider callback"]
@@ -66,7 +56,7 @@ flowchart LR
 - A fully local setup works: embedded Qdrant and local Ollama keep the data
   on your machine.
 - Data locality follows the destination. Extraction uses the LLM configured
-  in Hermes, and embedding uses the configured embedding service; either can
+  in Hermes, and embedding uses the configured embedding service. Either can
   be remote. See [Data flow and privacy](#data-flow-and-privacy).
 - Not supported in this preview: multi-writer Server/Cloud, hybrid search and
   a web UI.
@@ -75,9 +65,9 @@ flowchart LR
 
 The plugin primarily provides Hermes Agent's durable memory integration. As an
 additional capability, its shared backend can serve other agents through the
-Runtime 0.2.0's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
-interface, without requiring Hermes. These interfaces support explicit scoped
-memory operations and maintenance/migration; automatic extraction and prefetch
+Runtime's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
+interface. Standalone use does not require Hermes. These interfaces support explicit scoped
+memory operations and maintenance/migration. Automatic extraction and prefetch
 remain Hermes lifecycle features. See [standalone setup](docs/standalone.md) for
 configuration and boundaries, and the agent-neutral
 [qdrant-memory skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)
@@ -85,19 +75,20 @@ for multi-agent installation and usage guidance.
 
 The optional MCP server exposes four scoped tools: `qdrant_memory_search`,
 `qdrant_memory_add`, `qdrant_memory_update` and `qdrant_memory_delete`. Compatible
-clients launch it as a local stdio process and discover/call those tools;
-maintenance and migration use the operator CLI. See the
+clients launch it as a local stdio process and discover/call those tools.
+Maintenance and migration use the operator CLI. See the
 [MCP capabilities and connection guide](docs/mcp.md) for setup, shared-memory
-boundaries and the verified agent matrix. This is a tested source preview;
-the published v0.1.0 plugin release does not include the MCP entrypoint.
+boundaries and the verified agent matrix. Runtime 0.2.0 published these interfaces.
+The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ## See it in action
 
 ![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: install from the
-official Hermes Plugin Catalog, teach a preference, wait for the background
-extraction, recall it in a new session, and clean up the demo scope. All steps
+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
+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
 the pinned release.
 
@@ -128,14 +119,17 @@ 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 pinned release through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+
+This immutable source revision includes the explicit-write fix. 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 5babd3e4b4c022aad38a2b6db82cbd5b601f1ef8   # v0.1.0 release commit
+  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -144,12 +138,15 @@ hermes qdrant-memory init
 
 For this version-locked form, `hermes plugins install` checks out the given ref, and
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
-`--ref` takes a full 40-character commit SHA; the
+`--ref` takes a full 40-character commit SHA. The
 [releases page](https://github.com/cnkang/hermes-plugin-qdrant-memory/releases)
 lists the release commits. Do not pip-install into a managed Hermes
 environment. Omit `--ref` to track `main`, the development line.
 
-**Alternative: clone the release tag manually.**
+**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.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"
@@ -178,7 +175,7 @@ import and registration. For development installs, see
 [development setup](docs/development.md).
 
 The release notes, supported Hermes/Python versions and the current
-limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md);
+limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md).
 `main` stays the development line.
 
 For local development, symlink the repository into a disposable profile:
@@ -223,7 +220,10 @@ mappings) stays in the local Hermes home. Back up that home together with your
 Qdrant data. Migration from Mem0 is one-way, and version 0.1 has no vector
 reuse or hybrid retrieval.
 
-Similarity is a candidate-selection signal, not proof that two facts are identical.
+Explicit add deduplicates only canonical text in the same scope and never calls
+an LLM. Different texts are saved regardless of similarity. Update replaces only
+the authorized exact ID. For automatic Hermes extraction,
+similarity is a candidate-selection signal, not proof that two facts are identical.
 `SAME` skips, `SUPERSEDES` updates, `CONFLICT` creates a linked record, and
 `UNRELATED` adds a record. Migration uses source IDs instead of semantic merging.
 
@@ -305,7 +305,7 @@ default profile scope uses an agent (`hermes`). Pass `--agent hermes` to
 target it, or `--all-agents` to delete every agent scope of the user. Without
 `--all-agents`, the result reports `other_agent_scopes` when other agent
 scopes still hold memories. A literal `*` is an ordinary agent id, not a
-wildcard. `--dry-run` previews the per-scope counts;
+wildcard. `--dry-run` previews the per-scope counts.
 `--confirm` authorizes deletion. An interrupted deletion fails closed: other
 commands and provider startup return `scope_delete_recovery_required` until
 `delete-all --confirm` resumes it. Deletion intents are versioned and explicit.
@@ -313,8 +313,8 @@ A pre-versioned intent cannot show whether `*` is a single agent or all agents,
 so the plugin refuses it (`scope_delete_legacy_intent`). Resolve it with
 `--resolve-legacy single_agent`, or with `--resolve-legacy all_agents` when the
 record's agent is `*` or absent. Turns admitted after the deletion can still
-add new memories; everything admitted before it — stored memories, prepared
-writes and unprocessed turn events — is removed or invalidated. `list`,
+add new memories. Everything admitted before it, including stored memories, prepared
+writes and unprocessed turn events, is removed or invalidated. `list`,
 `export` and `delete-all` do not require the embedding service.
 
 ## Data flow and privacy
@@ -325,10 +325,10 @@ carries and where it can go:
 | Component | Carries | Destination |
 | --- | --- | --- |
 | Chat / agent turns | Your conversation | The model configured for the Hermes session |
-| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model — with a cloud model, turn text reaches that cloud |
-| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction; runs only when similarity selects a review candidate |
+| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model. With a cloud model, turn text reaches that cloud |
+| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction. It runs only when similarity selects a review candidate |
 | Embeddings (`embedding`) | Memory and search text | Ollama by default, or your OpenAI-compatible endpoint |
-| Storage (`qdrant`) | Memory payloads and provenance; the ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
+| Storage (`qdrant`) | Memory payloads and provenance. The ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
 
 Three common deployments:
 
@@ -483,7 +483,7 @@ contains `memories` objects with `id`/`text`, and `queries` with `query`/`releva
 The default fixture now contains 24 labeled queries, including Chinese, English,
 mixed-language and hard-negative cases. The
 [original 12-query recording](docs/retrieval-baseline.json) is a historical
-synthetic regression baseline; rerun the current fixture for current measurements.
+synthetic regression baseline. Rerun the current fixture for current measurements.
 These fixtures do not establish production recall quality. See the [recovery benchmark](docs/recovery-benchmark.md)
 for a separate synthetic replay and retained-storage measurement.
 

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

@@ -1,3 +1,24 @@
+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)
@@ -7,12 +28,11 @@
 [![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)
 
-> **v0.1.0 — limited technical preview.** Give Hermes Agent durable, private
-> long-term memory: your conversations become searchable memories in your own
-> Qdrant store, with recall, update and scoped deletion under your control.
-> The preview supports one writer per destination, with the documented
-> durability limits. See the [validation record](docs/validation.md) for the
-> current certification.
+> **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.
+> 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).
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
@@ -26,6 +46,16 @@ 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]`
+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).
+Public releases: [Runtime on PyPI](https://pypi.org/project/hermes-plugin-qdrant-memory/)
+and [MCP distribution on PyPI](https://pypi.org/project/qdrant-memory-mcp/).
+For native Hermes use its official plugin installation mechanism below. Before
+an authorized upgrade, verify the same profile, collection and embedding pipeline.
+
 ```mermaid
 flowchart LR
     turn["Hermes turn"] --> admit["Provider callback"]
@@ -47,7 +77,7 @@ flowchart LR
 - A fully local setup works: embedded Qdrant and local Ollama keep the data
   on your machine.
 - Data locality follows the destination. Extraction uses the LLM configured
-  in Hermes, and embedding uses the configured embedding service; either can
+  in Hermes, and embedding uses the configured embedding service. Either can
   be remote. See [Data flow and privacy](#data-flow-and-privacy).
 - Not supported in this preview: multi-writer Server/Cloud, hybrid search and
   a web UI.
@@ -56,9 +86,9 @@ flowchart LR
 
 The plugin primarily provides Hermes Agent's durable memory integration. As an
 additional capability, its shared backend can serve other agents through the
-Runtime 0.2.0's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
-interface, without requiring Hermes. These interfaces support explicit scoped
-memory operations and maintenance/migration; automatic extraction and prefetch
+Runtime's `qdrant-memory --home PATH` JSON CLI and optional local stdio MCP
+interface. Standalone use does not require Hermes. These interfaces support explicit scoped
+memory operations and maintenance/migration. Automatic extraction and prefetch
 remain Hermes lifecycle features. See [standalone setup](docs/standalone.md) for
 configuration and boundaries, and the agent-neutral
 [qdrant-memory skill](https://github.com/cnkang/skills/tree/main/qdrant-memory)
@@ -66,19 +96,20 @@ for multi-agent installation and usage guidance.
 
 The optional MCP server exposes four scoped tools: `qdrant_memory_search`,
 `qdrant_memory_add`, `qdrant_memory_update` and `qdrant_memory_delete`. Compatible
-clients launch it as a local stdio process and discover/call those tools;
-maintenance and migration use the operator CLI. See the
+clients launch it as a local stdio process and discover/call those tools.
+Maintenance and migration use the operator CLI. See the
 [MCP capabilities and connection guide](docs/mcp.md) for setup, shared-memory
-boundaries and the verified agent matrix. This is a tested source preview;
-the published v0.1.0 plugin release does not include the MCP entrypoint.
+boundaries and the verified agent matrix. Runtime 0.2.0 published these interfaces.
+The published v0.1.0 plugin release does not include the MCP entrypoint.
 
 ## See it in action
 
 ![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: install from the
-official Hermes Plugin Catalog, teach a preference, wait for the background
-extraction, recall it in a new session, and clean up the demo scope. All steps
+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
+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
 the pinned release.
 
@@ -109,14 +140,17 @@ 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 pinned release through the Hermes CLI.**
+**Version-locked: install the verified Runtime 0.2.1 source through the Hermes CLI.**
+
+This immutable source revision includes the explicit-write fix. 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 5babd3e4b4c022aad38a2b6db82cbd5b601f1ef8   # v0.1.0 release commit
+  --ref 8929693fcccd1efa91bfa062145e35d2369ca9cc   # verified Runtime 0.2.1 source
 hermes plugins enable qdrant-memory
 hermes memory setup
 hermes config set memory.provider qdrant-memory
@@ -125,12 +159,15 @@ hermes qdrant-memory init
 
 For this version-locked form, `hermes plugins install` checks out the given ref, and
 `hermes plugins enable` prepares the declared dependencies through Hermes PM.
-`--ref` takes a full 40-character commit SHA; the
+`--ref` takes a full 40-character commit SHA. The
 [releases page](https://github.com/cnkang/hermes-plugin-qdrant-memory/releases)
 lists the release commits. Do not pip-install into a managed Hermes
 environment. Omit `--ref` to track `main`, the development line.
 
-**Alternative: clone the release tag manually.**
+**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.
 
 ```bash
 export HERMES_HOME="/absolute/path/to/your/hermes-profile"
@@ -159,7 +196,7 @@ import and registration. For development installs, see
 [development setup](docs/development.md).
 
 The release notes, supported Hermes/Python versions and the current
-limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md);
+limitations live in [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md).
 `main` stays the development line.
 
 For local development, symlink the repository into a disposable profile:
@@ -204,7 +241,10 @@ mappings) stays in the local Hermes home. Back up that home together with your
 Qdrant data. Migration from Mem0 is one-way, and version 0.1 has no vector
 reuse or hybrid retrieval.
 
-Similarity is a candidate-selection signal, not proof that two facts are identical.
+Explicit add deduplicates only canonical text in the same scope and never calls
+an LLM. Different texts are saved regardless of similarity. Update replaces only
+the authorized exact ID. For automatic Hermes extraction,
+similarity is a candidate-selection signal, not proof that two facts are identical.
 `SAME` skips, `SUPERSEDES` updates, `CONFLICT` creates a linked record, and
 `UNRELATED` adds a record. Migration uses source IDs instead of semantic merging.
 
@@ -286,7 +326,7 @@ default profile scope uses an agent (`hermes`). Pass `--agent hermes` to
 target it, or `--all-agents` to delete every agent scope of the user. Without
 `--all-agents`, the result reports `other_agent_scopes` when other agent
 scopes still hold memories. A literal `*` is an ordinary agent id, not a
-wildcard. `--dry-run` previews the per-scope counts;
+wildcard. `--dry-run` previews the per-scope counts.
 `--confirm` authorizes deletion. An interrupted deletion fails closed: other
 commands and provider startup return `scope_delete_recovery_required` until
 `delete-all --confirm` resumes it. Deletion intents are versioned and explicit.
@@ -294,8 +334,8 @@ A pre-versioned intent cannot show whether `*` is a single agent or all agents,
 so the plugin refuses it (`scope_delete_legacy_intent`). Resolve it with
 `--resolve-legacy single_agent`, or with `--resolve-legacy all_agents` when the
 record's agent is `*` or absent. Turns admitted after the deletion can still
-add new memories; everything admitted before it — stored memories, prepared
-writes and unprocessed turn events — is removed or invalidated. `list`,
+add new memories. Everything admitted before it, including stored memories, prepared
+writes and unprocessed turn events, is removed or invalidated. `list`,
 `export` and `delete-all` do not require the embedding service.
 
 ## Data flow and privacy
@@ -306,10 +346,10 @@ carries and where it can go:
 | Component | Carries | Destination |
 | --- | --- | --- |
 | Chat / agent turns | Your conversation | The model configured for the Hermes session |
-| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model — with a cloud model, turn text reaches that cloud |
-| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction; runs only when similarity selects a review candidate |
+| Memory extraction (`llm.mode: inherit`) | The turn's user and assistant text | The same session model. With a cloud model, turn text reaches that cloud |
+| Relation checks | The candidate memory and the similar stored memory | Same routing as extraction. It runs only when similarity selects a review candidate |
 | Embeddings (`embedding`) | Memory and search text | Ollama by default, or your OpenAI-compatible endpoint |
-| Storage (`qdrant`) | Memory payloads and provenance; the ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
+| Storage (`qdrant`) | Memory payloads and provenance. The ledger stays local | Embedded local path, self-hosted server, or Qdrant Cloud |
 
 Three common deployments:
 
@@ -464,7 +504,7 @@ contains `memories` objects with `id`/`text`, and `queries` with `query`/`releva
 The default fixture now contains 24 labeled queries, including Chinese, English,
 mixed-language and hard-negative cases. The
 [original 12-query recording](docs/retrieval-baseline.json) is a historical
-synthetic regression baseline; rerun the current fixture for current measurements.
+synthetic regression baseline. Rerun the current fixture for current measurements.
 These fixtures do not establish production recall quality. See the [recovery benchmark](docs/recovery-benchmark.md)
 for a separate synthetic replay and retained-storage measurement.
 

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

@@ -41,6 +41,7 @@ tests/test_cli_output.py
 tests/test_config_embedding.py
 tests/test_deletion_ordering.py
 tests/test_discovery_cli.py
+tests/test_explicit_dedupe.py
 tests/test_host_lifecycle.py
 tests/test_input_validation.py
 tests/test_inventory_export.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hermes-plugin-qdrant-memory"
-version = "0.2.0"
+version = "0.2.1"
 description = "Durable Qdrant memory for Hermes, standalone CLI and local MCP"
 readme = "README.md"
 license = "MIT"
@@ -23,6 +23,8 @@ Homepage = "https://github.com/cnkang/hermes-plugin-qdrant-memory"
 Repository = "https://github.com/cnkang/hermes-plugin-qdrant-memory"
 Issues = "https://github.com/cnkang/hermes-plugin-qdrant-memory/issues"
 Changelog = "https://github.com/cnkang/hermes-plugin-qdrant-memory/blob/main/CHANGELOG.md"
+MCP = "https://github.com/cnkang/qdrant-memory-mcp"
+Skill = "https://github.com/cnkang/skills/tree/main/qdrant-memory"
 
 [project.entry-points."hermes_agent.memory_providers"]
 qdrant-memory = "qdrant_memory:register"

{hermes_plugin_qdrant_memory-0.2.0 → hermes_plugin_qdrant_memory-0.2.1}/qdrant_memory/dedupe.py

@@ -3,6 +3,14 @@
 from .models import content_hash
 
 
+def decide_explicit(text, scope, store):
+    """Deduplicate authorized explicit writes only by canonical hash in scope."""
+    exact = store.lookup_hash(scope, content_hash(text))
+    if exact:
+        return "SKIP", str(exact.id), {}
+    return "ADD", None, {}
+
+
 def decide(text, scope, store, extractor, cfg):
     """Return ADD, UPDATE or SKIP after scoped hash and factual relation checks.
 

{hermes_plugin_qdrant_memory-0.2.0 → hermes_plugin_qdrant_memory-0.2.1}/qdrant_memory/plugin.yaml

@@ -1,5 +1,5 @@
 name: qdrant-memory
-version: 0.2.0
+version: 0.2.1
 description: Durable native memory with Qdrant and Hermes LLM extraction
 manifest_version: 2
 author: Kang Liu

{hermes_plugin_qdrant_memory-0.2.0 → hermes_plugin_qdrant_memory-0.2.1}/qdrant_memory/runtime.py

@@ -5,7 +5,7 @@ import time
 from itertools import islice
 from threading import RLock
 
-from .dedupe import decide
+from .dedupe import decide, decide_explicit
 from .models import Scope, content_hash, enforce_limits, now, payload, point_id
 from .progress import report
 from .retry import run_with_retry
@@ -163,11 +163,9 @@ class Runtime:
         return failures
 
     def add(self, text, scope, source="manual_tool", session_id="", **fields):
-        """Add or reconcile a scoped fact through hash and factual relation review."""
+        """Save an explicit scoped fact with deterministic exact-text deduplication."""
         with self.lock:
-            action, identifier, relation = decide(
-                text, scope, self.store, self.extractor, self.cfg["dedupe"]
-            )
+            action, identifier, relation = decide_explicit(text, scope, self.store)
             self.decisions[action] += 1
             self.ledger.increment(action)
             if action == "SKIP":

{hermes_plugin_qdrant_memory-0.2.0 → hermes_plugin_qdrant_memory-0.2.1}/qdrant_memory/version.py

@@ -1,3 +1,3 @@
 """Single version source shared by registration and migration manifests."""
 
-VERSION = "0.2.0"
+VERSION = "0.2.1"

hermes_plugin_qdrant_memory-0.2.1/tests/test_explicit_dedupe.py

@@ -0,0 +1,80 @@
+"""Explicit intent and automatic factual adjudication remain separate policies."""
+
+import math
+
+import pytest
+
+from qdrant_memory.models import Scope
+from qdrant_memory.tools import dispatch
+
+from .helpers import LLM, runtime
+
+
+@pytest.mark.parametrize("score", [0.92, 0.97, 1.0])
+@pytest.mark.parametrize("with_extractor", [False, True])
+def test_explicit_add_keeps_distinct_similar_facts(tmp_path, score, with_extractor):
+    """Similarity cannot discard explicit intent, even when an LLM reports SAME."""
+    llm = LLM("SAME")
+    rt = runtime(tmp_path, llm=llm)
+    if not with_extractor:
+        rt.extractor = None
+    scope = Scope("alice", "hermes")
+    rt.store.embedder.embed_query = lambda text: (
+        [1.0, 0.0, 0.0] if "preferred" in text else [score, math.sqrt(1 - score**2), 0.0]
+    )
+    try:
+        first = dispatch(rt, "qdrant_memory_add", {"text": "cats preferred"}, scope, "s")
+        assert rt.store.search("cats avoided", scope)[0].score == pytest.approx(score)
+        second = dispatch(rt, "qdrant_memory_add", {"text": "cats avoided"}, scope, "s")
+        assert first["action"] == second["action"] == "ADD"
+        assert first["id"] != second["id"]
+        duplicate = rt.add("  cats   preferred  ", scope)
+        assert duplicate == {"action": "SKIP", "id": first["id"]}
+        for other in (Scope("bob", "hermes"), Scope("alice", "other")):
+            assert rt.add("cats preferred", other)["id"] != first["id"]
+            assert rt.store.count(other) == 1
+        assert rt.store.count(scope) == 2
+        assert not llm.calls
+    finally:
+        rt.store.close()
+        rt.ledger.close()
+
+
+@pytest.mark.parametrize(
+    "relation,count,texts",
+    [
+        ("SAME", 1, {"cats preferred"}),
+        ("SUPERSEDES", 1, {"cats avoided"}),
+        ("CONFLICT", 2, {"cats preferred", "cats avoided"}),
+        ("UNRELATED", 2, {"cats preferred", "cats avoided"}),
+    ],
+)
+def test_automatic_events_retain_factual_relations(tmp_path, relation, count, texts):
+    """Real extraction and durable event processing still adjudicate similar facts."""
+    llm = LLM(relation)
+    rt = runtime(tmp_path, llm=llm)
+    scope = Scope("alice", "hermes")
+    try:
+        first = rt.add("cats preferred", scope)
+        key = rt.ledger.enqueue_event(
+            {
+                "kind": "turn",
+                "scope": scope.as_dict(),
+                "source": "conversation",
+                "session_id": "s",
+                "user": "cats avoided",
+                "assistant": "ack",
+            }
+        )
+        rt.process_event(key)
+        assert rt.store.count(scope) == count
+        hits = rt.store.search("cats", scope)
+        assert {h.payload["text"] for h in hits} == texts
+        if relation == "CONFLICT":
+            conflict = next(h for h in hits if h.payload["text"] == "cats avoided")
+            assert conflict.payload["metadata"]["conflicts_with"] == first["id"]
+        assert any(c["purpose"] == "qdrant-memory.relation" for c in llm.calls)
+        assert rt.ledger.row("events", key)["status"] == "COMMITTED"
+    finally:
+        rt.store.close()
+        rt.ledger.close()

{hermes_plugin_qdrant_memory-0.2.0 → hermes_plugin_qdrant_memory-0.2.1}/tests/test_manifest_contract.py

@@ -17,6 +17,13 @@ def test_manifests_declare_v2_metadata_and_match_runtime_dependencies():
 
     assert manifests[0] == manifests[1]
     manifest = manifests[0]
+    from qdrant_memory.version import VERSION
+
+    assert str(manifest["version"]) == project["version"] == VERSION
+    for name in ("README.md", "README.zh-CN.md", "docs/standalone.md", "docs/mcp.md"):
+        text = (ROOT / name).read_text(encoding="utf-8")
+        assert f"hermes-plugin-qdrant-memory[mcp]=={VERSION}" in text
+        assert "hermes-plugin-qdrant-memory[mcp]==0.2.0" not in text
     assert manifest["manifest_version"] == 2
     assert manifest["author"] == "Kang Liu"
     assert manifest["license"] == "MIT"