memplex 3.2.0__tar.gz

memplex-3.2.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: memplex
+Version: 3.2.0
+Summary: Memplex - Memory Complex: multi-agent knowledge graph memory system with 3-layer retrieval
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: embedding
+Requires-Dist: sentence-transformers>=2.0; extra == "embedding"
+Provides-Extra: extractors
+Requires-Dist: pdfplumber>=0.9.0; extra == "extractors"
+Requires-Dist: python-docx>=0.8.11; extra == "extractors"
+Requires-Dist: Pillow>=9.0; extra == "extractors"
+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: graph
+Requires-Dist: networkx>=3.0; extra == "graph"
+Requires-Dist: python-louvain>=0.16; extra == "graph"
+Provides-Extra: http
+Requires-Dist: fastapi>=0.100.0; extra == "http"
+Requires-Dist: uvicorn>=0.23.0; extra == "http"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.30.0; extra == "llm"
+Requires-Dist: openai>=1.0.0; extra == "llm"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0.0; extra == "neo4j"
+Provides-Extra: all
+Requires-Dist: memnex[embedding,extractors,graph,http,llm,vector]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"

memplex-3.2.0/memnex/__init__.py

@@ -0,0 +1,31 @@
+"""MemNex -- multi-agent memory system.
+
+Primary entry point::
+
+    from memnex import MemNexService
+
+    svc = MemNexService()
+    result = svc.query("登录函数在哪")
+
+CLI usage::
+
+    memnex query "search text"
+    memnex write --text "content"
+    memnex health
+"""
+
+from memnex.core import CoreEngine
+from memnex.service import MemNexService
+
+__all__ = ["CoreEngine", "MemNexService", "main"]
+
+
+def main() -> None:
+    """CLI entry point for ``memnex`` command.
+
+    Delegates to :func:`memnex.adapters.cli.main`.
+    """
+    import sys
+    from memnex.adapters.cli import main as cli_main
+
+    sys.exit(cli_main())

memplex-3.2.0/memnex/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m memnex``."""
+
+import sys
+from memnex.adapters.cli import main
+
+sys.exit(main())

memplex-3.2.0/memnex/_plugin/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "memplex",
+  "version": "3.2.0",
+  "description": "Multi-agent memory system -- persistent knowledge graph with 3-layer retrieval, compaction, and wiki",
+  "author": {
+    "name": "articultur"
+  },
+  "repository": "https://github.com/articultur/MemNex",
+  "license": "Apache-2.0",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "plugin",
+    "memory",
+    "knowledge-graph",
+    "retrieval",
+    "compaction",
+    "wiki",
+    "python",
+    "fastapi"
+  ],
+  "homepage": "https://github.com/articultur/MemNex#readme"
+}

memplex-3.2.0/memnex/_plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "memnex": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "memnex.adapters.mcp_server"]
+    }
+  }
+}

memplex-3.2.0/memnex/_plugin/hooks/hooks.json

@@ -0,0 +1,43 @@
+{
+  "description": "MemNex memory system hooks",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "export PATH=\"$($SHELL -lc 'echo $PATH' 2>/dev/null):$PATH\"; MEMNEX_ROOT=\"${MEMNEX_PLUGIN_ROOT:-$(cd \"$(dirname \"$0\")/..\" && pwd)}\"; python \"$MEMNEX_ROOT/scripts/hook-runner.py\" session-start",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "export PATH=\"$($SHELL -lc 'echo $PATH' 2>/dev/null):$PATH\"; MEMNEX_ROOT=\"${MEMNEX_PLUGIN_ROOT:-$(cd \"$(dirname \"$0\")/..\" && pwd)}\"; python \"$MEMNEX_ROOT/scripts/hook-runner.py\" observation \"$MEMNEX_TOOL_NAME\" \"$MEMNEX_SESSION_ID\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "export PATH=\"$($SHELL -lc 'echo $PATH' 2>/dev/null):$PATH\"; MEMNEX_ROOT=\"${MEMNEX_PLUGIN_ROOT:-$(cd \"$(dirname \"$0\")/..\" && pwd)}\"; python \"$MEMNEX_ROOT/scripts/hook-runner.py\" session-stop",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

memplex-3.2.0/memnex/_plugin/scripts/hook-runner.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""MemNex Hook Runner -- dispatches lifecycle hooks for Claude Code.
+
+Called by plugin/hooks/hooks.json with subcommands:
+    session-start   - Load project context on session start
+    observation     - Auto-collect observation from tool usage
+    session-stop    - Compact session, update stats on stop
+
+Usage:
+    python hook-runner.py session-start
+    python hook-runner.py observation <tool_name> <session_id>
+    python hook-runner.py session-stop
+
+Exit codes (Claude Code hook contract):
+    0 - Success (output may be injected as context)
+    1 - Non-blocking error (stderr shown, continues)
+    2 - Blocking error (stderr fed to Claude)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+# Ensure memnex package is importable when run from plugin directory
+_PLUGIN_DIR = Path(__file__).resolve().parent
+_PROJECT_ROOT = _PLUGIN_DIR.parent.parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+_RATE_FILE = Path("/tmp/.memnex_last_obs")
+_RATE_LIMIT_SECONDS = 30
+_PRIVATE_TAG_RE = re.compile(r"<private>.*?</private>", re.DOTALL)
+
+
+def _strip_private_tags(text: str) -> str:
+    return _PRIVATE_TAG_RE.sub("", text)
+
+
+def _get_store_path() -> Optional[Path]:
+    project_root = os.environ.get("MEMNEX_PROJECT_ROOT", "")
+    if project_root:
+        p = Path(project_root) / ".memnex" / "memory.json"
+        if p.parent.exists():
+            return p
+    cwd = Path.cwd()
+    p = cwd / ".memnex" / "memory.json"
+    return p if p.parent.exists() else None
+
+
+def _init_service():
+    from memnex.config import load_config
+    from memnex.service import MemNexService
+
+    cfg = load_config()
+    return MemNexService(config=cfg)
+
+
+def cmd_session_start() -> None:
+    """Load project context and inject relevant memories."""
+    try:
+        service = _init_service()
+        result = service.query(text="", top_k=5)
+        if result.results:
+            lines = ["[MemNex Context] Top recent memories:"]
+            for r in result.results[:5]:
+                lines.append(f"  - {r.name} (domain: {r.domain}, relevance: {r.relevance_score:.2f})")
+            output = "\n".join(lines)
+            print(output)
+        else:
+            print("[MemNex] No memories stored yet for this project.")
+    except Exception as e:
+        print(f"[MemNex] session-start error: {e}", file=sys.stderr)
+    sys.exit(0)
+
+
+def cmd_observation(tool_name: str = "", session_id: str = "") -> None:
+    """Auto-collect observation from tool usage."""
+    if not tool_name:
+        tool_name = os.environ.get("MEMNEX_TOOL_NAME", "unknown")
+
+    # Rate limit
+    if _RATE_FILE.exists():
+        try:
+            last = float(_RATE_FILE.read_text().strip())
+            if time.time() - last < _RATE_LIMIT_SECONDS:
+                sys.exit(0)
+        except (ValueError, OSError):
+            pass
+
+    # Read tool input from stdin (Claude Code provides it)
+    tool_input = ""
+    try:
+        if not sys.stdin.isatty():
+            raw = sys.stdin.read()
+            data = json.loads(raw) if raw.strip() else {}
+            tool_input = json.dumps(data, ensure_ascii=False)[:500]
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    tool_input = _strip_private_tags(tool_input)
+    if not tool_input:
+        sys.exit(0)
+
+    obs_text = f"[{tool_name}] {tool_input}"
+
+    try:
+        service = _init_service()
+        service.write_text(text=obs_text, source_type="observation")
+    except Exception:
+        pass  # Non-blocking -- never fail the hook
+
+    # Update rate limit
+    try:
+        _RATE_FILE.write_text(str(time.time()))
+    except OSError:
+        pass
+
+    sys.exit(0)
+
+
+def cmd_session_stop() -> None:
+    """Compact session observations and update stats."""
+    try:
+        service = _init_service()
+        health = service.health()
+        stats = service.stats()
+
+        summary = json.dumps({
+            "status": health.get("status", "unknown"),
+            "total_memories": stats.get("total_functions", 0),
+            "total_edges": stats.get("total_edges", 0),
+        }, ensure_ascii=False)
+        print(f"[MemNex] Session ended. {summary}")
+    except Exception as e:
+        print(f"[MemNex] session-stop error: {e}", file=sys.stderr)
+    sys.exit(0)
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: hook-runner.py <command> [args]", file=sys.stderr)
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "session-start":
+        cmd_session_start()
+    elif command == "observation":
+        tool_name = sys.argv[2] if len(sys.argv) > 2 else ""
+        session_id = sys.argv[3] if len(sys.argv) > 3 else ""
+        cmd_observation(tool_name, session_id)
+    elif command == "session-stop":
+        cmd_session_stop()
+    else:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

memplex-3.2.0/memnex/_plugin/skills/mem-explore/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: mem-explore
+description: Explore MemNex knowledge graph. Use when user asks "what do we know about X?", "explore memories", "show related concepts", or wants to browse the knowledge base.
+---
+
+# Memory Explore
+
+Browse and explore the MemNex knowledge graph to understand related concepts and connections.
+
+## When to Use
+
+Use when users want to explore stored knowledge:
+
+- "What do we know about X?"
+- "Show me everything related to Y"
+- "Explore the knowledge graph"
+- "What memories are in the database?"
+
+## Workflow
+
+### Broad Exploration
+
+Search with a general query to discover what's stored:
+
+```
+memory_search(query="authentication", top_k=20)
+```
+
+### Drill Down
+
+Pick interesting results and fetch details:
+
+```
+memory_get(memory_id="func_abc123")
+```
+
+### Check Health and Stats
+
+Use CLI to see overall state:
+
+```bash
+# Service health
+memnex health
+
+# Statistics (total memories, types breakdown, graph edges)
+memnex stats
+```
+
+### Review Pending Conflicts
+
+Check if any memories need resolution:
+
+```
+memory_pending_reviews(limit=20)
+```
+
+Resolve conflicts:
+
+```
+memory_resolve(memory_id="func_abc123", field_role="action", action="accept")
+```
+
+## Understanding Memory Structure
+
+Each memory has metadata:
+
+- **version**: Incremented on merge/update
+- **confidence**: 0.0-1.0 quality score
+- **access_count**: How often this memory has been retrieved
+- **domain**: Category (security, testing, devops, etc.)
+- **source_type**: Where it came from (wiki, file, url, text)
+
+## Graph Relationships
+
+MemNex auto-detects three edge types:
+
+| Edge | Meaning |
+|------|---------|
+| REFERENCES | Memory A references Memory B |
+| DEPENDS_ON | Memory A depends on Memory B |
+| CONFLICTS_WITH | Memory A contradicts Memory B |
+
+These are discovered during write operations via term mapping, reference linking, entity alignment, and domain classification.

memplex-3.2.0/memnex/_plugin/skills/mem-manage/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: mem-manage
+description: Manage MemNex memory system. Use when user asks to "compact memories", "cleanup database", "memory stats", "run compaction", or perform maintenance operations.
+---
+
+# Memory Manage
+
+Perform maintenance and management operations on the MemNex knowledge base.
+
+## When to Use
+
+Use when users want to maintain or manage memories:
+
+- "Compact the memory database"
+- "Clean up old memories"
+- "Show me memory stats"
+- "Run compaction"
+- "Check memory health"
+
+## Operations
+
+### Health Check
+
+```
+memory_health()
+```
+
+Or via CLI:
+
+```bash
+memnex health
+```
+
+### Statistics
+
+```bash
+memnex stats
+```
+
+Shows total memories, breakdown by type, graph edges, storage size.
+
+### Run Compaction
+
+5-stage pipeline: Extract → Dedup → Summarize → Prune → Archive
+
+```bash
+# Compact project-level memories
+memnex compact --scope project
+
+# Compact all memories
+memnex compact --scope global
+```
+
+Compaction automatically:
+- Deduplicates memories with similar names
+- Summarizes verbose field values
+- Prunes low-confidence entries
+- Archives stale memories
+
+### Submit Feedback
+
+Improve memory quality over time:
+
+```
+memory_feedback(memory_id="func_abc123", role="trigger", index=0, verdict="correct")
+memory_feedback(memory_id="func_abc123", role="action", index=1, verdict="wrong", reason="Should be POST not GET")
+```
+
+### Delete Memories
+
+```
+memory_delete(memory_id="func_abc123")
+```
+
+Or via CLI:
+
+```bash
+memnex delete func_abc123
+```
+
+### Update Memory Fields
+
+```
+memory_update(memory_id="func_abc123", role="action", new_value="Use OAuth2 with PKCE flow")
+```
+
+## Notes
+
+- Compaction is safe: it creates backups before modifying
+- Feedback weights affect future retrieval relevance
+- Delete is permanent -- use with care
+- Stats refresh after each operation

memplex-3.2.0/memnex/_plugin/skills/mem-search/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: mem-search
+description: Search MemNex persistent memory. Use when user asks "did we already solve this?", "how did we do X?", "recall", "lookup", or needs work from previous sessions.
+---
+
+# Memory Search
+
+Search MemNex knowledge graph across all sessions. Simple workflow: search → filter → fetch.
+
+## When to Use
+
+Use when users ask about PREVIOUS sessions or stored knowledge (not current conversation):
+
+- "Did we already fix this?"
+- "How did we solve X last time?"
+- "What do we know about Y?"
+- "Recall the steps for Z"
+
+## 3-Layer Workflow (ALWAYS Follow)
+
+**NEVER fetch full details without filtering first. 10x token savings.**
+
+### Step 1: Search -- Get Index with IDs
+
+Use the `memory_search` MCP tool:
+
+```
+memory_search(query="authentication", top_k=20)
+```
+
+**Returns:** Table with IDs, names, relevance scores, domains (~50-100 tokens/result)
+
+```
+| ID | Name | Relevance | Domain |
+|----|------|-----------|--------|
+| func_abc123 | JWT Auth Flow | 0.92 | security |
+| func_def456 | Token Refresh | 0.85 | security |
+```
+
+**Parameters:**
+
+- `query` (string) - Natural language search query
+- `top_k` (number) - Max results, default 10
+
+### Step 2: Filter -- Review Results
+
+Review names and relevance scores from Step 1. Pick relevant IDs. Discard the rest.
+
+### Step 3: Fetch -- Get Full Details ONLY for Filtered IDs
+
+Use the `memory_get` MCP tool:
+
+```
+memory_get(memory_id="func_abc123")
+```
+
+**Returns:** Complete memory object with trigger, condition, action, benefit fields, plus metadata
+
+## Examples
+
+**Find recent knowledge about a topic:**
+
+```
+memory_search(query="authentication", top_k=20)
+```
+
+**Get details for specific memories:**
+
+```
+memory_get(memory_id="func_abc123")
+memory_get(memory_id="func_def456")
+```
+
+**Submit feedback on a memory:**
+
+```
+memory_feedback(memory_id="func_abc123", role="trigger", index=0, verdict="correct")
+memory_feedback(memory_id="func_abc123", role="action", index=1, verdict="wrong")
+```
+
+## Why This Workflow?
+
+- **Search index:** ~50-100 tokens per result
+- **Full memory:** ~500-1000 tokens each
+- **10x token savings** by filtering before fetching

memplex-3.2.0/memnex/_plugin/skills/mem-write/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mem-write
+description: Store knowledge into MemNex memory. Use when user says "remember this", "save this", "memorize", "store", or provides documents/URLs/content for future reference.
+---
+
+# Memory Write
+
+Store knowledge into MemNex for persistent cross-session retrieval.
+
+## When to Use
+
+Use when users want to save knowledge for later:
+
+- "Remember this: ..."
+- "Save this for later"
+- "Store this document/URL"
+- "Memorize these steps"
+
+## Workflow
+
+### Store Text Content
+
+Use the `memory_add` MCP tool:
+
+```
+memory_add(content="Steps to deploy: 1) Run tests 2) Build 3) Push to main", source_type="text")
+```
+
+**Returns:** Extracted function IDs, graph edges created
+
+```
+{
+  "functions_extracted": 2,
+  "edges": 3,
+  "function_ids": ["func_abc123", "func_def456"]
+}
+```
+
+### Store from File
+
+Use the CLI:
+
+```bash
+memnex write --file /path/to/document.md
+```
+
+### Store from URL
+
+Use the CLI:
+
+```bash
+memnex write --url https://example.com/docs
+```
+
+### Review What Was Stored
+
+After writing, use `memory_get` to verify the extracted knowledge:
+
+```
+memory_get(memory_id="func_abc123")
+```
+
+## What Gets Stored
+
+MemNex extracts structured knowledge into 4 memory types:
+
+| Type | Structure | Example |
+|------|-----------|---------|
+| Function | trigger → condition → action → benefit | "When deploying, if tests pass, run build, to ship faster" |
+| Fact | subject → predicate → object | "Python uses GIL for thread safety" |
+| Preference | aspect → preference | "User prefers pytest over unittest" |
+| Observation | event → context | "Bug in auth module at line 42" |
+
+## Notes
+
+- Content is deduplicated automatically (same name → merge)
+- Graph edges (REFERENCES, DEPENDS_ON, CONFLICTS_WITH) are auto-detected
+- Private content wrapped in `<private>...</private>` is stripped before storage

memplex-3.2.0/memnex/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""MemNex Agent Adapters -- protocol-specific interfaces.
+
+Provides adapters for different consumption patterns:
+
+- CLI:     command-line interface (``memnex`` command)
+- HTTP:    REST API via FastAPI (``create_app`` factory)
+- MCP:     Model Context Protocol server over stdio JSON-RPC
+"""
+
+from memnex.adapters.cli import main as cli_main
+from memnex.adapters.http_api import create_app
+from memnex.adapters.mcp_server import MCPServer
+
+__all__ = ["cli_main", "create_app", "MCPServer"]