memplex 3.2.4__tar.gz → 3.2.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memplex
-Version: 3.2.4
+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.7/README.md

@@ -0,0 +1,186 @@
+# Memplex
+
+Memplex is a shared long-term memory layer for AI agents. It gives Codex,
+Claude Code, OpenClaw, Hermes, and similar local agents the same closed loop:
+recall useful memory before a turn, capture what happened after the turn, and
+compact old context in the background.
+
+## Install
+
+No source checkout is required.
+
+```bash
+npx memplex setup
+```
+
+Install into a specific agent:
+
+```bash
+npx memplex setup --agent codex --project-path "$PWD"
+npx memplex setup --agent claude-code --project-path "$PWD"
+npx memplex setup --agent openclaw --project-path "$PWD"
+npx memplex setup --agent hermes --project-path "$PWD"
+```
+
+Install every supported local agent:
+
+```bash
+npx memplex setup --agent all --project-path "$PWD"
+```
+
+Uninstall is symmetrical:
+
+```bash
+npx memplex uninstall --agent all
+```
+
+The npm wrapper creates a persistent Python environment at
+`~/.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.7
+memplex setup --agent all --project-path "$PWD"
+```
+
+Shell-only fallback:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/articultur/memplex/main/scripts/install-agent.sh | bash
+```
+
+## What Gets Installed
+
+| Agent | Integration | Installed shape |
+| --- | --- | --- |
+| Codex | MCP server | marker-bounded `mcp_servers.memplex` config |
+| Claude Code | plugin + lifecycle hooks + MCP | packaged plugin and hook runner |
+| OpenClaw | memory plugin slot | `plugins.slots.memory = "memplex"` plus extension files |
+| Hermes | memory provider plugin | provider descriptor and `plugins/memory/memplex` |
+
+All installers are reversible and refuse to overwrite unmanaged existing
+Memplex entries.
+
+## Verify
+
+List supported profiles:
+
+```bash
+memplex --output json agent list
+```
+
+Run a local closed-loop smoke:
+
+```bash
+memplex --output json agent capture \
+  --agent codex \
+  --user-message "Use lite storage for local development." \
+  --assistant-message "Recorded."
+
+memplex --output json agent recall \
+  --agent codex \
+  "What storage should local development use?"
+```
+
+For a no-write preview:
+
+```bash
+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**: 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.
+- **Wiki layer**: full-text/vector retrieval plus graph-aware synthesis.
+- **Namespacing**: user, session, project path, and storage path isolation.
+
+## Docs
+
+- [Getting Started](docs/getting-started.md): install, verify, uninstall, and
+  troubleshoot.
+- [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.
+- [Release Automation](docs/release-automation.md): npm token handling and
+  automated npm publishing.
+
+## From Source
+
+```bash
+git clone https://github.com/articultur/memplex.git
+cd memplex
+pip install -e .
+```
+
+## CLI Basics
+
+```bash
+memplex write --text "Python list comprehensions are faster than loops"
+memplex query "python performance"
+memplex compact
+memplex health
+```
+
+## Storage And Privacy
+
+The default local backend is a JSON-backed LiteMemoryStore at
+`.memplex/memory.json`. Memplex can also use vector and feedback backends when
+configured.
+
+Content wrapped in `<private>...</private>` is not stored.
+
+## License
+
+MIT

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

@@ -1,6 +1,6 @@
 {
   "name": "memplex",
-  "version": "3.2.4",
+  "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.4 → 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.4 → memplex-3.2.7}/memplex/adapters/agent_installer.py

@@ -938,9 +938,21 @@ def _marketplace_json() -> str:
 
 
 def _package_version() -> str:
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            import tomllib
+
+            data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+            project = data.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
 
     try:
         return pkg_version("memplex")
     except Exception:
-        return "3.2.4"
+        return "3.2.7"

{memplex-3.2.4 → memplex-3.2.7}/memplex/adapters/agent_runtime.py

@@ -235,9 +235,7 @@ class AgentMemoryRuntime:
         self.auto_recall = auto_recall
         capabilities = AGENT_PROFILES[self.agent].capabilities
         self.prefetch_enabled = (
-            capabilities.get("zero_latency_prefetch", False)
-            if prefetch is None
-            else prefetch
+            capabilities.get("zero_latency_prefetch", False) if prefetch is None else prefetch
         )
         self._prefetch_cache = _PREFETCH_CACHE
 
@@ -338,10 +336,7 @@ class AgentMemoryRuntime:
         wrapped = IndirectInjectionGuard.filter_and_wrap(result.results, self.service.store)
         if wrapped:
             return wrapped
-        lines = []
-        for item in result.results:
-            lines.append(f"[MEMORY id={item.func_id}] {item.summary}")
-        return "\n".join(lines)
+        return "[MEMORY FILTERED | reason=indirect_injection]\nUnsafe recalled memory was omitted."
 
     @staticmethod
     def _query_from_prompt(prompt: str) -> str:

{memplex-3.2.4 → 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.4 → memplex-3.2.7}/memplex/adapters/mcp_server.py

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

{memplex-3.2.4 → 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.4 → 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]: