memplex 3.2.0__py3-none-any.whl

memnex/adapters/claude_skill.py

@@ -0,0 +1,169 @@
+"""MemNex Claude Skill Adapter -- generates SKILL.md and hook scripts.
+
+Generates files that integrate MemNex into Claude Code's skill system:
+
+- ``SKILL.md``: skill description with YAML frontmatter and trigger conditions
+- ``hook.sh``: PostToolUse hook script that auto-collects observations
+
+Usage::
+
+    from memnex.adapters.claude_skill import generate_skill_md, generate_hook_sh
+
+    skill_content = generate_skill_md()
+    hook_content = generate_hook_sh()
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import Optional
+
+
+_SKILL_MD_TEMPLATE = textwrap.dedent("""\
+    ---
+    name: memnex
+    description: Search and manage MemNex persistent memory. Use when user asks to "search memory", "recall", "remember this", "save", "lookup", or needs knowledge from previous sessions.
+    ---
+
+    # MemNex Memory Skill
+
+    Persistent knowledge graph for multi-agent workflows. Store, query, and
+    manage knowledge that persists across sessions.
+
+    ## When to Use
+
+    Activate when the user:
+    - Asks to find or recall information from past sessions
+    - Provides content and asks to "remember" or "save" it
+    - Wants to review, correct, or update existing memories
+    - Uses keywords: "memnex", "memory", "remember", "recall", "lookup"
+
+    ## 3-Layer Retrieval (ALWAYS Follow)
+
+    **NEVER fetch full details without filtering first.**
+
+    ### Step 1: Search -- Get Index with IDs
+
+    Use the `memory_search` MCP tool:
+
+    ```
+    memory_search(query="search text", top_k=10)
+    ```
+
+    Returns: IDs, names, relevance scores (~50-100 tokens/result)
+
+    ### Step 2: Filter -- Review Results
+
+    Pick relevant IDs from search results. Discard the rest.
+
+    ### Step 3: Fetch -- Get Full Details for Filtered IDs
+
+    ```
+    memory_get(memory_id="func_abc123")
+    ```
+
+    Returns: Complete memory with all fields (~500-1000 tokens)
+
+    ## Write Memory
+
+    ```
+    memory_add(content="text to remember", source_type="text")
+    ```
+
+    ## Feedback and Maintenance
+
+    ```
+    memory_feedback(memory_id="...", role="trigger", index=0, verdict="correct")
+    memory_pending_reviews(limit=20)
+    memory_health()
+    ```
+
+    ## CLI Commands
+
+    ```bash
+    memnex query "search text"       # Search memories
+    memnex write --text "content"    # Write memory
+    memnex get <memory_id>           # Get details
+    memnex health                    # Health check
+    memnex stats                     # Statistics
+    memnex compact --scope project   # Run compaction
+    ```
+""")
+
+
+def generate_skill_md(output_path: Optional[str] = None) -> str:
+    content = _SKILL_MD_TEMPLATE.strip() + "\n"
+
+    if output_path is not None:
+        import os
+        os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    return content
+
+
+_HOOK_SH_TEMPLATE = textwrap.dedent("""\
+    #!/usr/bin/env bash
+    # MemNex PostToolUse Hook -- auto-collect observations
+    #
+    # Register in plugin/hooks/hooks.json.
+    #
+    # Environment variables provided by Claude Code:
+    #   MEMNEX_TOOL_NAME    - name of the tool that was called
+    #   MEMNEX_SESSION_ID   - current session identifier
+
+    set -euo pipefail
+
+    # Rate limit: skip if last observation was less than 30 seconds ago
+    RATE_FILE="/tmp/.memnex_last_obs_${MEMNEX_SESSION_ID:-default}"
+    if [ -f "$RATE_FILE" ]; then
+        LAST=$(cat "$RATE_FILE" 2>/dev/null || echo 0)
+        NOW=$(date +%s)
+        DIFF=$((NOW - LAST))
+        if [ "$DIFF" -lt 30 ]; then
+            exit 0
+        fi
+    fi
+
+    TOOL_NAME="${MEMNEX_TOOL_NAME:-unknown}"
+    TOOL_INPUT="${MEMNEX_TOOL_INPUT:-}"
+
+    # Skip low-value tools
+    case "$TOOL_NAME" in
+        Read|read) exit 0 ;;
+    esac
+
+    # Build observation text from tool input
+    OBS_TEXT="[$TOOL_NAME] $TOOL_INPUT"
+
+    # Truncate to reasonable length
+    if [ ${#OBS_TEXT} -gt 500 ]; then
+        OBS_TEXT="${OBS_TEXT:0:500}..."
+    fi
+
+    # Store observation via CLI
+    if command -v memnex &>/dev/null; then
+        memnex write --text "$OBS_TEXT" --output json 2>/dev/null || true
+    fi
+
+    # Update rate limit timestamp
+    date +%s > "$RATE_FILE"
+""")
+
+
+def generate_hook_sh(output_path: Optional[str] = None) -> str:
+    content = _HOOK_SH_TEMPLATE.strip() + "\n"
+
+    if output_path is not None:
+        import os
+        import stat
+
+        os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        st = os.stat(output_path)
+        os.chmod(output_path, st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    return content

memnex/adapters/cli.py

@@ -0,0 +1,525 @@
+"""MemNex CLI -- command-line interface using argparse.
+
+Usage::
+
+    memnex query "login function"
+    memnex write --text "some observation"
+    memnex write --file ./notes.txt
+    memnex write --url https://example.com/doc
+    memnex get func_abc123
+    memnex delete func_abc123
+    memnex feedback func_abc123 --role trigger --index 0 --verdict correct
+    memnex pending
+    memnex compact --scope project
+    memnex health
+    memnex stats
+    memnex setup            # Install as Claude Code plugin
+    memnex unsetup          # Uninstall Claude Code plugin
+
+Global options::
+
+    --config <path>     Path to config YAML file
+    --output json|table Output format (default: table)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Optional, Sequence
+
+
+# ── Helpers ─────────────────────────────────────────────────────────
+
+
+def _make_service(config_path: Optional[str] = None):
+    """Create and return a MemNexService instance."""
+    from memnex.config import load_config
+    from memnex.service import MemNexService
+
+    config = load_config(path=config_path)
+    return MemNexService(config=config)
+
+
+def _fmt(data, output: str) -> str:
+    """Format *data* for the chosen output mode."""
+    if output == "json":
+        return json.dumps(data, indent=2, default=str, ensure_ascii=False)
+
+    # table / plain text
+    if isinstance(data, list):
+        if not data:
+            return "(empty)"
+        lines = []
+        for item in data:
+            if isinstance(item, dict):
+                lines.append(_dict_to_table(item))
+            else:
+                lines.append(str(item))
+        return "\n---\n".join(lines)
+
+    if isinstance(data, dict):
+        return _dict_to_table(data)
+
+    return str(data)
+
+
+def _dict_to_table(d: dict, indent: int = 0) -> str:
+    """Recursively format a dict as indented key-value lines."""
+    prefix = "  " * indent
+    lines = []
+    for k, v in d.items():
+        if isinstance(v, dict):
+            lines.append(f"{prefix}{k}:")
+            lines.append(_dict_to_table(v, indent + 1))
+        elif isinstance(v, list):
+            lines.append(f"{prefix}{k}:")
+            for item in v:
+                if isinstance(item, dict):
+                    lines.append(_dict_to_table(item, indent + 1))
+                else:
+                    lines.append(f"{prefix}  - {item}")
+        else:
+            lines.append(f"{prefix}{k}: {v}")
+    return "\n".join(lines)
+
+
+def _result_to_dict(result) -> dict:
+    """Convert a SearchResult / QueryResult / dataclass to a dict."""
+    if hasattr(result, "__dataclass_fields__"):
+        return asdict(result)
+    if isinstance(result, dict):
+        return result
+    return {"value": str(result)}
+
+
+def _dataclass_to_dict(obj):
+    """Recursively convert dataclasses to dicts."""
+    if hasattr(obj, "__dataclass_fields__"):
+        return asdict(obj)
+    if isinstance(obj, list):
+        return [_dataclass_to_dict(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: _dataclass_to_dict(v) for k, v in obj.items()}
+    return obj
+
+
+# ── Command implementations ────────────────────────────────────────
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    """Execute a memory query."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        result = svc.query(
+            text=args.text,
+            top_k=getattr(args, "top_k", 10),
+        )
+
+        out = []
+        for r in result.results:
+            out.append({
+                "id": r.func_id,
+                "name": r.name,
+                "relevance": round(r.relevance_score, 4),
+                "summary": r.summary,
+                "scope": r.domain,
+            })
+
+        print(_fmt({
+            "total": len(out),
+            "scope": result.scope.value if hasattr(result.scope, "value") else str(result.scope),
+            "latency_ms": result.latency_ms,
+            "results": out,
+        }, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_write(args: argparse.Namespace) -> int:
+    """Write new content into memory."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        if args.text:
+            content = args.text
+            source_type = "text"
+        elif args.file:
+            with open(args.file, "r", encoding="utf-8") as f:
+                content = f.read()
+            source_type = "file"
+        elif args.url:
+            content = args.url
+            source_type = "url"
+        else:
+            print("Error: provide --text, --file, or --url", file=sys.stderr)
+            return 1
+
+        result = svc.write_text(text=content, source_type=source_type)
+
+        out = {
+            "functions_extracted": len(result.functions),
+            "edges": len(result.graph.edges),
+            "function_ids": [f.id for f in result.functions],
+        }
+        print(_fmt(out, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_get(args: argparse.Namespace) -> int:
+    """Retrieve a single memory by ID."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        func = svc.get(args.memory_id)
+        if func is None:
+            print(f"Memory not found: {args.memory_id}", file=sys.stderr)
+            return 1
+
+        print(_fmt(_dataclass_to_dict(func), args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_delete(args: argparse.Namespace) -> int:
+    """Delete a memory by ID."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        svc.delete(args.memory_id)
+        print(_fmt({"status": "deleted", "id": args.memory_id}, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_feedback(args: argparse.Namespace) -> int:
+    """Submit feedback for a memory field value."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        svc.submit_feedback(
+            memory_id=args.memory_id,
+            field_role=args.role,
+            value_index=args.index,
+            verdict=args.verdict,
+        )
+        print(_fmt({
+            "status": "recorded",
+            "memory_id": args.memory_id,
+            "role": args.role,
+            "index": args.index,
+            "verdict": args.verdict,
+        }, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_pending(args: argparse.Namespace) -> int:
+    """List pending reviews."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        reviews = svc.get_pending_reviews()
+        out = [_dataclass_to_dict(r) for r in reviews]
+        print(_fmt({"total": len(out), "reviews": out}, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_compact(args: argparse.Namespace) -> int:
+    """Run the compaction pipeline."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        result = svc.compact(scope=getattr(args, "scope", "project"))
+        out = _dataclass_to_dict(result)
+        print(_fmt(out, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+def cmd_health(args: argparse.Namespace) -> int:
+    """Health check."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        info = svc.health()
+        print(_fmt(info, args.output))
+        return 0 if info.get("status") == "ok" else 1
+    finally:
+        svc.stop()
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    """Display statistics."""
+    svc = _make_service(getattr(args, "config", None))
+    try:
+        info = svc.stats()
+        print(_fmt(info, args.output))
+        return 0
+    finally:
+        svc.stop()
+
+
+# ── Claude Code Plugin Setup ────────────────────────────────────────
+
+_PLUGIN_AUTHOR = "articultur"
+_PLUGIN_NAME = "memnex"
+_MARKETPLACE_JSON = """{
+  "name": "memplex",
+  "interface": {
+    "displayName": "Memplex (local)"
+  },
+  "plugins": [
+    {
+      "name": "memplex",
+      "source": {
+        "source": "local",
+        "path": "./plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+"""
+
+
+def _get_plugin_source_dir() -> Path:
+    """Find the plugin directory within the memnex package."""
+    # Installed via pip: use bundled memnex/_plugin/
+    package_dir = Path(__file__).resolve().parent.parent
+    bundled = package_dir / "_plugin"
+    if bundled.exists() and (bundled / "hooks").exists():
+        return bundled
+    # Development mode: use project root plugin/
+    dev_plugin = package_dir / "plugin"
+    if dev_plugin.exists() and (dev_plugin / "hooks").exists():
+        return dev_plugin
+    raise FileNotFoundError("Cannot find plugin directory in memnex package")
+
+
+def _get_marketplace_dir() -> Path:
+    """Return the Claude Code marketplace target directory."""
+    claude_dir = Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude"))
+    return claude_dir / "plugins" / "marketplaces" / _PLUGIN_AUTHOR
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """Install MemNex as a Claude Code plugin."""
+    market_dir = _get_marketplace_dir()
+    plugin_target = market_dir / "plugin"
+
+    print("Memplex Plugin Setup")
+    print("=" * 40)
+
+    # 1. Check Python dependencies
+    print("\n[1/4] Checking dependencies...")
+    try:
+        import yaml  # noqa: F401
+        import numpy  # noqa: F401
+        print("  Core dependencies: OK")
+    except ImportError as e:
+        print(f"  Missing dependency: {e}")
+        print(f"  Run: pip install memnex[embedding]")
+        return 1
+
+    # 2. Find and copy plugin directory
+    print("\n[2/4] Installing plugin files...")
+    try:
+        source = _get_plugin_source_dir()
+    except FileNotFoundError as e:
+        print(f"  Error: {e}")
+        return 1
+
+    if plugin_target.exists():
+        shutil.rmtree(plugin_target)
+
+    def _ignore_patterns(_dir, files):
+        return [f for f in files if f == "__pycache__" or f.endswith(".pyc")]
+
+    shutil.copytree(source, plugin_target, symlinks=False, ignore=_ignore_patterns)
+    print(f"  Installed to: {plugin_target}")
+
+    # 3. Write marketplace.json
+    print("\n[3/4] Registering with Claude Code...")
+    market_json = market_dir / "marketplace.json"
+    market_dir.mkdir(parents=True, exist_ok=True)
+    market_json.write_text(_MARKETPLACE_JSON.strip() + "\n")
+    print(f"  Marketplace: {market_json}")
+
+    # 4. Write install marker
+    print("\n[4/4] Writing install marker...")
+    marker = market_dir / ".install-version"
+    from importlib.metadata import version as pkg_version
+    try:
+        ver = pkg_version("memnex")
+    except Exception:
+        ver = "3.2.0"
+    marker.write_text(json.dumps({
+        "version": ver,
+        "installedAt": __import__("datetime").datetime.now().isoformat(),
+    }, indent=2))
+    print(f"  Version: {ver}")
+
+    print("\n" + "=" * 40)
+    print("Memplex plugin installed successfully!")
+    print("\nWhat was configured:")
+    print(f"  - Hooks:    {plugin_target}/hooks/hooks.json")
+    print(f"  - MCP:      {plugin_target}/.mcp.json")
+    print(f"  - Skills:   {plugin_target}/skills/*/SKILL.md")
+    print(f"  - Manifest: {plugin_target}/../.claude-plugin/plugin.json")
+    print("\nRestart Claude Code to activate the plugin.")
+    return 0
+
+
+def cmd_unsetup(args: argparse.Namespace) -> int:
+    """Uninstall MemNex Claude Code plugin."""
+    market_dir = _get_marketplace_dir()
+
+    print("Memplex Plugin Uninstall")
+    print("=" * 40)
+
+    if not market_dir.exists():
+        print("  Plugin not installed (directory not found).")
+        return 0
+
+    shutil.rmtree(market_dir)
+    print(f"  Removed: {market_dir}")
+    print("\nMemplex plugin uninstalled. Restart Claude Code to apply.")
+    return 0
+
+
+# ── Argument parser ────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build and return the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="memnex",
+        description="MemNex -- multi-agent memory system",
+    )
+    parser.add_argument("--config", default=None, help="Path to config YAML file")
+    parser.add_argument(
+        "--output",
+        choices=["json", "table"],
+        default="table",
+        help="Output format (default: table)",
+    )
+
+    sub = parser.add_subparsers(dest="command", help="Available commands")
+
+    # -- query --
+    p_query = sub.add_parser("query", help="Query memory")
+    p_query.add_argument("text", help="Query text")
+    p_query.add_argument("--top-k", type=int, default=10, help="Max results")
+
+    # -- write --
+    p_write = sub.add_parser("write", help="Write content to memory")
+    p_write.add_argument("--text", help="Raw text to write")
+    p_write.add_argument("--file", help="File path to read and write")
+    p_write.add_argument("--url", help="URL to write")
+
+    # -- get --
+    p_get = sub.add_parser("get", help="Get memory by ID")
+    p_get.add_argument("memory_id", help="Memory ID")
+
+    # -- delete --
+    p_del = sub.add_parser("delete", help="Delete memory by ID")
+    p_del.add_argument("memory_id", help="Memory ID")
+
+    # -- 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("--index", type=int, required=True, help="Value index")
+    p_fb.add_argument(
+        "--verdict",
+        required=True,
+        choices=["correct", "wrong"],
+        help="Verdict",
+    )
+
+    # -- pending --
+    sub.add_parser("pending", help="List pending reviews")
+
+    # -- compact --
+    p_compact = sub.add_parser("compact", help="Run compaction pipeline")
+    p_compact.add_argument(
+        "--scope",
+        default="project",
+        choices=["session", "project", "global"],
+        help="Compaction scope (default: project)",
+    )
+
+    # -- health --
+    sub.add_parser("health", help="Health check")
+
+    # -- stats --
+    sub.add_parser("stats", help="Show statistics")
+
+    # -- setup --
+    p_setup = sub.add_parser("setup", help="Install MemNex as a Claude Code plugin")
+    p_setup.add_argument("--uninstall", action="store_true", help="Uninstall the plugin")
+
+    # -- unsetup --
+    sub.add_parser("unsetup", help="Uninstall MemNex Claude Code plugin")
+
+    return parser
+
+
+# ── Entry point ─────────────────────────────────────────────────────
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """CLI entry point.
+
+    Parameters
+    ----------
+    argv:
+        Argument list.  Defaults to ``sys.argv[1:]``.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    dispatch = {
+        "query": cmd_query,
+        "write": cmd_write,
+        "get": cmd_get,
+        "delete": cmd_delete,
+        "feedback": cmd_feedback,
+        "pending": cmd_pending,
+        "compact": cmd_compact,
+        "health": cmd_health,
+        "stats": cmd_stats,
+        "setup": cmd_setup,
+        "unsetup": cmd_unsetup,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return 1
+
+    try:
+        return handler(args)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())