memplex 3.2.5__tar.gz → 3.2.7__tar.gz

{memplex-3.2.5 → memplex-3.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memplex
-Version: 3.2.5
+Version: 3.2.7
 Summary: Memplex - Memory Complex: multi-agent knowledge graph memory system with 3-layer retrieval
 Requires-Python: >=3.11
 License-File: LICENSE
@@ -17,6 +17,9 @@ Requires-Dist: pytesseract>=0.3.10; extra == "extractors"
 Provides-Extra: vector
 Requires-Dist: chromadb>=0.4.0; extra == "vector"
 Requires-Dist: sentence-transformers>=2.0; extra == "vector"
+Provides-Extra: local-onnx
+Requires-Dist: onnxruntime>=1.17.0; extra == "local-onnx"
+Requires-Dist: tokenizers>=0.15.0; extra == "local-onnx"
 Provides-Extra: graph
 Requires-Dist: networkx>=3.0; extra == "graph"
 Requires-Dist: python-louvain>=0.16; extra == "graph"
@@ -31,7 +34,7 @@ Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
 Provides-Extra: neo4j
 Requires-Dist: neo4j>=5.0.0; extra == "neo4j"
 Provides-Extra: all
-Requires-Dist: memplex[embedding,extractors,graph,http,llm,vector]; extra == "all"
+Requires-Dist: memplex[embedding,extractors,graph,http,llm,local-onnx,vector]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

{memplex-3.2.5 → memplex-3.2.7}/README.md

@@ -35,14 +35,14 @@ npx memplex uninstall --agent all
 ```
 
 The npm wrapper creates a persistent Python environment at
-`~/.local/share/memplex/agent-venv`, installs `memplex==3.2.5`, detects local
+`~/.local/share/memplex/agent-venv`, installs `memplex==3.2.7`, detects local
 agent config directories, and registers Memplex into the selected hosts. It uses
 `uv` when available and falls back to `python -m venv` plus `pip`.
 
 Python-first users can skip npm:
 
 ```bash
-uv tool install memplex==3.2.5
+uv tool install memplex==3.2.7
 memplex setup --agent all --project-path "$PWD"
 ```
 
@@ -91,12 +91,55 @@ For a no-write preview:
 npx memplex setup --agent all --project-path "$PWD" --dry-run
 ```
 
+## Offline And Mainland China
+
+Memplex's default local retrieval uses a SQLite FTS5 sidecar index with
+`bm25()` ranking plus generated trigram tokens for Chinese, code symbols,
+paths, and short memory fragments. If SQLite FTS5 is unavailable, it falls back
+to pure-Python local BM25/trigram matching. The agent hot path does not need
+HuggingFace, so `npx memplex setup`, capture, recall, MCP tools, and hooks
+continue to work when HuggingFace is blocked or unavailable.
+
+The embedding fallback is also local. To force that path explicitly:
+
+```bash
+MEMPLEX_EMBEDDING_MODEL=tfidf memplex query "local memory"
+```
+
+To enhance semantic recall with a local model and no network downloads:
+
+```bash
+python -m pip install "memplex[local-onnx]"
+export MEMPLEX_LOCAL_ONNX_MODEL=/models/bge-small/model.onnx
+export MEMPLEX_LOCAL_ONNX_TOKENIZER=/models/bge-small/tokenizer.json
+memplex query "local semantic memory"
+```
+
+`MEMPLEX_EMBEDDING_MODEL=local-onnx` or
+`MEMPLEX_EMBEDDING_MODEL=local-onnx:/models/bge-small/model.onnx` opts in
+explicitly and reports configuration errors. With the default auto-enhancement
+path, a missing local ONNX runtime or model keeps the SQLite
+FTS5/BM25+trigram retrieval path alive and falls back to local embedding.
+
+Opt into HuggingFace only when the environment can reach it or the model is
+already cached:
+
+```bash
+MEMPLEX_EMBEDDING_MODEL=minilm memplex query "semantic memory"
+MEMPLEX_EMBEDDING_MODEL=bge-m3 memplex query "中文记忆"
+MEMPLEX_EMBEDDING_MODEL=hf:BAAI/bge-m3 memplex query "中文记忆"
+```
+
+If your organization provides an approved HuggingFace mirror, configure it in
+the Python/HuggingFace environment before enabling those models. Otherwise keep
+the default local retrieval and embedding path for agent reliability.
+
 ## Core Features
 
 - **Automatic agent loop**: pre-turn recall, post-turn capture, background
   consolidation.
 - **4 memory types**: Function, Fact, Preference, Observation.
-- **3-layer retrieval**: search, timeline, get.
+- **3-layer retrieval**: SQLite FTS5/BM25+trigram search, timeline, get.
 - **5-dim reranking**: raw relevance, semantic similarity, recency, source
   authority, frequency.
 - **5-stage compaction**: extract, dedup, summarize, prune, archive.
@@ -110,8 +153,8 @@ npx memplex setup --agent all --project-path "$PWD" --dry-run
 - [Explainer](docs/explainer.md): what Memplex is and how the memory loop works.
 - [Agent Integration Loop](docs/agent-integration.md): adapter contracts for
   Codex, Claude Code, OpenClaw, and Hermes.
-- [Hot-Path Smoke Plan](docs/agent-hot-path-smoke.md): how real agent runtime
-  paths are tested.
+- [Release Automation](docs/release-automation.md): npm token handling and
+  automated npm publishing.
 
 ## From Source
 

{memplex-3.2.5 → memplex-3.2.7}/memplex/_plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memplex",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "Multi-agent memory system -- persistent knowledge graph with 3-layer retrieval, compaction, and wiki",
   "author": {
     "name": "articultur"

{memplex-3.2.5 → memplex-3.2.7}/memplex/_plugin/scripts/hook-runner.py

@@ -199,6 +199,31 @@ def _print_contract(content: str = "") -> None:
     print(OUTPUT_CONTRACT)
 
 
+def _package_version(memplex_module: Any) -> str:
+    """Resolve package version, preferring source-tree pyproject metadata."""
+    try:
+        import tomllib
+
+        for parent in Path(__file__).resolve().parents:
+            pyproject = parent / "pyproject.toml"
+            if not pyproject.exists():
+                continue
+            project = tomllib.loads(pyproject.read_text(encoding="utf-8")).get(
+                "project", {}
+            )
+            if project.get("name") == "memplex" and project.get("version"):
+                return str(project["version"])
+    except Exception:
+        pass
+
+    try:
+        from importlib.metadata import version as pkg_version
+
+        return pkg_version("memplex")
+    except Exception:
+        return getattr(memplex_module, "__version__", "unknown")
+
+
 def cmd_setup() -> None:
     """Check environment on plugin install."""
     try:
@@ -207,7 +232,7 @@ def cmd_setup() -> None:
         from memplex.config import load_config
 
         # Verify memplex is importable
-        version = getattr(memplex, "__version__", "unknown")
+        version = _package_version(memplex)
 
         # Check config
         try:
@@ -219,6 +244,7 @@ def cmd_setup() -> None:
         # Initialize service if config exists
         if cfg:
             from memplex.service import MemplexService
+
             service = MemplexService(config=cfg)
             health = service.health()
             print(f"[Memplex] v{version} installed. Status: {health.get('status', 'unknown')}")

{memplex-3.2.5 → memplex-3.2.7}/memplex/adapters/agent_installer.py

@@ -955,4 +955,4 @@ def _package_version() -> str:
     try:
         return pkg_version("memplex")
     except Exception:
-        return "3.2.5"
+        return "3.2.7"

{memplex-3.2.5 → memplex-3.2.7}/memplex/adapters/cli.py

@@ -268,7 +268,7 @@ def cmd_health(args: argparse.Namespace) -> int:
     try:
         info = svc.health()
         print(_fmt(info, args.output))
-        return 0 if info.get("status") == "ok" else 1
+        return 0 if info.get("status") in {"healthy", "warning"} else 1
     finally:
         svc.stop()
 
@@ -477,9 +477,7 @@ def build_parser() -> argparse.ArgumentParser:
     # -- feedback --
     p_fb = sub.add_parser("feedback", help="Submit feedback on a memory field")
     p_fb.add_argument("memory_id", help="Memory ID")
-    p_fb.add_argument(
-        "--role", required=True, help="Field role (trigger|action|condition|benefit)"
-    )
+    p_fb.add_argument("--role", required=True, help="Field role (trigger|action|condition|benefit)")
     p_fb.add_argument("--index", type=int, required=True, help="Value index")
     p_fb.add_argument(
         "--verdict",
@@ -508,9 +506,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     # -- agent --
     p_agent = sub.add_parser("agent", help="Portable agent integration commands")
-    agent_sub = p_agent.add_subparsers(
-        dest="agent_command", help="Agent integration command"
-    )
+    agent_sub = p_agent.add_subparsers(dest="agent_command", help="Agent integration command")
     agent_sub.add_parser("list", help="List supported agent profiles")
 
     p_agent_manifest = agent_sub.add_parser("manifest", help="Show agent manifest")
@@ -520,9 +516,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Agent id: codex | claude-code | openclaw | hermes | all",
     )
 
-    p_agent_install = agent_sub.add_parser(
-        "install", help="Install Memplex into an agent host"
-    )
+    p_agent_install = agent_sub.add_parser("install", help="Install Memplex into an agent host")
     p_agent_install.add_argument(
         "--agent",
         default="all",
@@ -565,9 +559,7 @@ def build_parser() -> argparse.ArgumentParser:
     p_agent_recall.add_argument("--top-k", type=int, default=5)
     p_agent_recall.add_argument("--token-budget", type=int, default=1500)
 
-    p_agent_capture = agent_sub.add_parser(
-        "capture", help="Capture a completed agent turn"
-    )
+    p_agent_capture = agent_sub.add_parser("capture", help="Capture a completed agent turn")
     p_agent_capture.add_argument("--agent", default="codex")
     p_agent_capture.add_argument("--user-id", default=None)
     p_agent_capture.add_argument("--session-id", default="default")

{memplex-3.2.5 → memplex-3.2.7}/memplex/adapters/mcp_server.py

@@ -331,7 +331,7 @@ class MCPServer:
             },
             "serverInfo": {
                 "name": "memplex",
-                "version": "3.2.5",
+                "version": "3.2.7",
             },
         }
 

{memplex-3.2.5 → memplex-3.2.7}/memplex/config.py

@@ -29,7 +29,7 @@ class StorageConfig:
 class EmbeddingConfig:
     """Embedding model configuration."""
 
-    model: str = "default"  # default | bge-m3 | bge-small | openai
+    model: str = "default"  # default=local, optional local ONNX; hf:<id>=HF
     dimension: int = 384
     batch_size: int = 32
     contextual_retrieval: bool = True
@@ -263,9 +263,7 @@ def _apply_env_overrides(config: MemplexConfig) -> None:
     # Handle LLM fallback_chain via MEMPLEX_LLM_FALLBACK_CHAIN (comma-separated)
     fallback_env = os.environ.get("MEMPLEX_LLM_FALLBACK_CHAIN")
     if fallback_env is not None:
-        config.llm.fallback_chain = [
-            s.strip() for s in fallback_env.split(",") if s.strip()
-        ]
+        config.llm.fallback_chain = [s.strip() for s in fallback_env.split(",") if s.strip()]
 
 
 # ── YAML loading helpers ────────────────────────────────────────

{memplex-3.2.5 → memplex-3.2.7}/memplex/core/associator/term_mapper.py

@@ -1,10 +1,13 @@
 """Term-based association using dictionary lookup."""
 
+import logging
 from typing import List, Optional, Set, Tuple
 
 from memplex.core.dictionaries import TermDictionary
 from memplex.models.memory import Function
 
+logger = logging.getLogger(__name__)
+
 
 class TermMapper:
     """Maps terms between documents using dictionary lookup."""
@@ -13,7 +16,7 @@ class TermMapper:
         self.dictionary = dictionary or TermDictionary()
 
     def embed_text(self, text: str) -> Optional[List[float]]:
-        """Generate embedding vector using sentence-transformers (if available)."""
+        """Generate embedding vector using sentence-transformers when available."""
         try:
             from sentence_transformers import SentenceTransformer
 
@@ -22,6 +25,10 @@ class TermMapper:
             embedding = self._embedding_model.encode([text])[0]
             return embedding.tolist()
         except ImportError:
+            logger.debug("sentence-transformers not installed; skipping term embedding")
+            return None
+        except Exception as exc:
+            logger.debug("Term embedding unavailable: %s", exc)
             return None
 
     def extract_terms(self, text: str) -> Set[str]:

{memplex-3.2.5 → memplex-3.2.7}/memplex/retrieval/embedding.py

@@ -1,7 +1,8 @@
 """EmbeddingService -- vector embedding generation, storage and refresh.
 
-Supports multiple embedding models, configurable dimension, batch size,
-and Contextual Retrieval (Anthropic's document-context prefix injection).
+Supports an offline default embedder, optional HuggingFace-backed models,
+optional local ONNX models, configurable dimension, batch size, and Contextual
+Retrieval (Anthropic's document-context prefix injection).
 
 Embedding strategies::
 
@@ -20,7 +21,9 @@ Usage::
 from __future__ import annotations
 
 import logging
+import os
 from enum import Enum
+from pathlib import Path
 from typing import TYPE_CHECKING, List, Optional
 
 from memplex.models import Function, RefreshResult
@@ -56,6 +59,7 @@ class _SentenceTransformerEmbedder:
     def __init__(self, model_name: str, dimension: int) -> None:
         from sentence_transformers import SentenceTransformer  # type: ignore
 
+        self.model_name = model_name
         self._model = SentenceTransformer(model_name)
         self.dimension = dimension
 
@@ -68,7 +72,7 @@ class _SentenceTransformerEmbedder:
 
 
 class _SimpleTFIDFEmbedder:
-    """Fallback embedder when sentence-transformers is unavailable.
+    """Local embedder used for offline/default operation.
 
     Uses a TF-IDF-inspired bag-of-words representation.  The dimension
     is fixed to the number of unique words seen so far (padded / truncated
@@ -117,6 +121,104 @@ class _SimpleTFIDFEmbedder:
         return [self.encode(t) for t in texts]
 
 
+class _LocalONNXEmbedder:
+    """Offline ONNX embedding backend for locally cached models."""
+
+    def __init__(
+        self,
+        model_path: str,
+        dimension: int,
+        tokenizer_path: Optional[str] = None,
+        max_length: int = 256,
+    ) -> None:
+        import numpy as np
+        import onnxruntime as ort  # type: ignore
+        from tokenizers import Tokenizer  # type: ignore
+
+        resolved_model = Path(model_path).expanduser()
+        if not resolved_model.exists():
+            raise FileNotFoundError(f"Local ONNX model not found: {resolved_model}")
+
+        resolved_tokenizer = (
+            Path(tokenizer_path).expanduser()
+            if tokenizer_path
+            else resolved_model.parent / "tokenizer.json"
+        )
+        if not resolved_tokenizer.exists():
+            raise FileNotFoundError(
+                f"Local ONNX tokenizer not found: {resolved_tokenizer}"
+            )
+
+        self.model_path = str(resolved_model)
+        self.dimension = dimension
+        self.max_length = max(1, max_length)
+        self._np = np
+        self._tokenizer = Tokenizer.from_file(str(resolved_tokenizer))
+        self._session = ort.InferenceSession(
+            str(resolved_model),
+            providers=["CPUExecutionProvider"],
+        )
+        self._input_names = [item.name for item in self._session.get_inputs()]
+
+    def encode(self, text: str) -> Vector:
+        inputs = self._encode_inputs(text)
+        outputs = self._session.run(None, inputs)
+        return self._normalize_output(outputs[0], inputs.get("attention_mask"))
+
+    def encode_batch(self, texts: List[str], batch_size: int = 32) -> List[Vector]:
+        return [self.encode(text) for text in texts]
+
+    def _encode_inputs(self, text: str) -> dict:
+        encoding = self._tokenizer.encode(text)
+        ids = list(getattr(encoding, "ids", []) or [])[: self.max_length]
+        if not ids:
+            ids = [0]
+        attention_mask = [1] * len(ids)
+
+        inputs = {}
+        if "input_ids" in self._input_names:
+            inputs["input_ids"] = self._np.array([ids], dtype=self._np.int64)
+        if "attention_mask" in self._input_names:
+            inputs["attention_mask"] = self._np.array(
+                [attention_mask],
+                dtype=self._np.int64,
+            )
+        if "token_type_ids" in self._input_names:
+            inputs["token_type_ids"] = self._np.zeros(
+                (1, len(ids)),
+                dtype=self._np.int64,
+            )
+        if not inputs:
+            inputs[self._input_names[0]] = self._np.array([ids], dtype=self._np.int64)
+        return inputs
+
+    def _normalize_output(self, output, attention_mask=None) -> Vector:
+        arr = self._np.asarray(output, dtype=float)
+        if arr.ndim == 3:
+            token_embeddings = arr[0]
+            if attention_mask is not None:
+                mask = self._np.asarray(attention_mask[0], dtype=float)[:, None]
+                denom = max(float(mask.sum()), 1.0)
+                vec = (token_embeddings * mask).sum(axis=0) / denom
+            else:
+                vec = token_embeddings.mean(axis=0)
+        elif arr.ndim == 2:
+            vec = arr[0]
+        else:
+            vec = arr.reshape(-1)
+
+        values = [float(value) for value in vec.tolist()]
+        if len(values) < self.dimension:
+            values.extend([0.0] * (self.dimension - len(values)))
+        elif len(values) > self.dimension:
+            values = values[: self.dimension]
+
+        norm = sum(value * value for value in values) ** 0.5
+        if norm > 0:
+            values = [value / norm for value in values]
+        return values
+
+
 # ── EmbeddingService ─────────────────────────────────────────────────
 
 
@@ -126,9 +228,14 @@ class EmbeddingService:
     Parameters
     ----------
     model:
-        Embedding model name.  ``"default"`` maps to
-        ``all-MiniLM-L6-v2``.  Falls back to TF-IDF when
-        sentence-transformers is not installed.
+        Embedding model name. ``"default"`` uses local retrieval and local
+        embeddings, and auto-enables local ONNX only when
+        ``MEMPLEX_LOCAL_ONNX_MODEL`` points at an existing local model.
+        ``"tfidf"``, ``"offline"``, and ``"lite"`` force local TF-IDF
+        embeddings. Use ``"local-onnx"``, ``"local-onnx:<path>``, or
+        ``"onnx:<path>"`` for a local ONNX model. Use ``"minilm"``,
+        ``"bge-m3"``, ``"bge-small"``, a raw sentence-transformers model id, or
+        ``"hf:<model-id>"`` to opt into HuggingFace-backed embeddings.
     dimension:
         Embedding vector dimension.
     storage:
@@ -137,8 +244,12 @@ class EmbeddingService:
         Optional :class:`VectorStore` for upsert operations.
     """
 
+    _OFFLINE_MODELS = {"default", "tfidf", "offline", "lite", "local"}
+    _HF_PREFIX = "hf:"
+    _LOCAL_ONNX_MODELS = {"local-onnx", "onnx"}
+    _LOCAL_ONNX_PREFIXES = ("local-onnx:", "onnx:")
     _MODEL_MAP = {
-        "default": "all-MiniLM-L6-v2",
+        "minilm": "sentence-transformers/all-MiniLM-L6-v2",
         "bge-m3": "BAAI/bge-m3",
         "bge-small": "BAAI/bge-small-en-v1.5",
     }
@@ -258,7 +369,52 @@ class EmbeddingService:
 
     def _create_embedder(self, model: str, dimension: int):
         """Create the appropriate embedder backend."""
-        model_name = self._MODEL_MAP.get(model, model)
+        model_key = (model or "default").strip()
+        model_lookup_key = model_key.lower()
+
+        onnx_model_path, onnx_explicit = self._resolve_local_onnx_model_path(
+            model_key,
+            model_lookup_key,
+        )
+        if onnx_model_path:
+            try:
+                return _LocalONNXEmbedder(
+                    model_path=onnx_model_path,
+                    tokenizer_path=os.getenv("MEMPLEX_LOCAL_ONNX_TOKENIZER"),
+                    max_length=self._local_onnx_max_length(),
+                    dimension=dimension,
+                )
+            except Exception as exc:
+                if onnx_explicit:
+                    raise RuntimeError(
+                        f"Failed to load explicit local ONNX embedding model "
+                        f"{onnx_model_path}: {exc}"
+                    ) from exc
+                logger.warning(
+                    "Failed to load local ONNX embedding model %s: %s. "
+                    "Falling back to TF-IDF embedder",
+                    onnx_model_path,
+                    exc,
+                )
+                return _SimpleTFIDFEmbedder(dimension=dimension)
+
+        if onnx_explicit:
+            raise ValueError(
+                "Local ONNX embedding requested but no model path was provided. "
+                "Set MEMPLEX_LOCAL_ONNX_MODEL or use "
+                "MEMPLEX_EMBEDDING_MODEL=local-onnx:/path/to/model.onnx."
+            )
+
+        if model_lookup_key in self._OFFLINE_MODELS:
+            logger.debug(
+                "Using local TF-IDF embedder for embedding model %s", model_key
+            )
+            return _SimpleTFIDFEmbedder(dimension=dimension)
+
+        if model_lookup_key.startswith(self._HF_PREFIX):
+            model_name = model_key[len(self._HF_PREFIX) :]
+        else:
+            model_name = self._MODEL_MAP.get(model_lookup_key, model_key)
 
         try:
             return _SentenceTransformerEmbedder(model_name, dimension)
@@ -275,3 +431,30 @@ class EmbeddingService:
                 exc,
             )
             return _SimpleTFIDFEmbedder(dimension=dimension)
+
+    @classmethod
+    def _resolve_local_onnx_model_path(
+        cls,
+        model_key: str,
+        model_lookup_key: str,
+    ) -> tuple[str, bool]:
+        """Resolve a local ONNX model path from model string or environment."""
+        for prefix in cls._LOCAL_ONNX_PREFIXES:
+            if model_lookup_key.startswith(prefix):
+                return model_key.split(":", 1)[1].strip(), True
+
+        if model_lookup_key in cls._LOCAL_ONNX_MODELS:
+            return os.getenv("MEMPLEX_LOCAL_ONNX_MODEL", "").strip(), True
+
+        if model_lookup_key == "default":
+            return os.getenv("MEMPLEX_LOCAL_ONNX_MODEL", "").strip(), False
+
+        return "", False
+
+    @staticmethod
+    def _local_onnx_max_length() -> int:
+        """Return local ONNX tokenizer max length from environment."""
+        try:
+            return int(os.getenv("MEMPLEX_LOCAL_ONNX_MAX_LENGTH", "256"))
+        except ValueError:
+            return 256

{memplex-3.2.5 → memplex-3.2.7}/memplex/service.py

@@ -25,7 +25,6 @@ import concurrent.futures
 import logging
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime
-from importlib.metadata import version as pkg_version
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -62,6 +61,26 @@ logger = logging.getLogger(__name__)
 # ── Helper ─────────────────────────────────────────────────────────────
 
 
+def _package_version() -> str:
+    """Resolve Memplex version, preferring source-tree pyproject metadata."""
+    try:
+        import tomllib
+
+        pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+        if pyproject.exists():
+            project = tomllib.loads(pyproject.read_text(encoding="utf-8")).get(
+                "project", {}
+            )
+            if project.get("name") == "memplex" and project.get("version"):
+                return str(project["version"])
+    except Exception:
+        pass
+
+    from importlib.metadata import version as pkg_version
+
+    return pkg_version("memplex")
+
+
 def _detect_memory_type(text: str) -> str:
     """Heuristic: classify text into a memory type.
 
@@ -1051,7 +1070,7 @@ class MemplexService:
         dead_letters_pending = self._worker.dead_letters_pending()
 
         # Version
-        version = pkg_version("memplex")
+        version = _package_version()
 
         return {
             "status": status,