zer0lint 0.1.0__py3-none-any.whl

zer0lint/__init__.py

@@ -0,0 +1,8 @@
+"""zer0lint — mem0 extraction optimizer."""
+
+__version__ = "0.1.0"
+__author__ = "Hermes Labs"
+__description__ = (
+    "Diagnostic and optimization tool for mem0 extraction pipelines. "
+    "Inspects your system, generates custom extraction prompts, tests them."
+)

zer0lint/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for zer0lint CLI."""
+
+from zer0lint.cli import app
+
+if __name__ == "__main__":
+    app()

zer0lint/analyzer.py

@@ -0,0 +1,73 @@
+"""Generate extraction prompt from environment signals."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def analyze_with_llm(llm: object, environment_summary: str) -> str:
+    """
+    Use LLM to generate a domain-specific extraction prompt from environment signals.
+
+    Args:
+        llm: mem0's configured LLM instance (any provider)
+        environment_summary: Text describing the system environment (from scanner)
+
+    Returns:
+        A domain-specific extraction prompt tailored to the environment
+    """
+
+    analysis_prompt = f"""You are an expert at designing memory extraction prompts for AI agents.
+
+Here is a description of the system environment you're designing a prompt for:
+
+---
+{environment_summary}
+---
+
+Based on this environment, write a mem0 custom_fact_extraction_prompt that will capture
+the most important facts this system needs to remember.
+
+The prompt should:
+1. Identify 5-8 specific categories of facts this system deals with
+2. Be specific to the actual work (not generic)
+3. Include 2-3 concrete examples (Input → Output in JSON)
+4. End with: Return facts as JSON with key "facts" and a list of strings. Extract generously.
+
+Return ONLY the prompt text. No explanation, no markdown, no preamble. Start writing now:"""
+
+    try:
+        response = llm.chat_completion(
+            messages=[{"role": "user", "content": analysis_prompt}],
+            temperature=0.3,
+        )
+        if isinstance(response, dict):
+            prompt_text = response.get("message", response.get("content", ""))
+        else:
+            prompt_text = str(response)
+        return prompt_text.strip()
+    except Exception as e:
+        raise RuntimeError(f"LLM analysis failed: {e}")
+
+
+def fallback_prompt_from_patterns(patterns: dict[str, list[str]]) -> str:
+    """
+    Generate a basic extraction prompt from detected patterns when LLM is unavailable.
+    """
+    if not patterns:
+        return (
+            "Extract all factual information from the conversation. "
+            "Return as JSON with key 'facts' and a list of strings. Extract generously."
+        )
+
+    categories_text = "\n".join(
+        f"{i+1}. {cat.capitalize()}: {', '.join(words)}"
+        for i, (cat, words) in enumerate(patterns.items())
+    )
+
+    return f"""You are a memory organizer for a system that works with {', '.join(patterns.keys())} data.
+
+Extract ALL significant facts from the conversation. Focus on:
+{categories_text}
+
+Return facts as JSON with key "facts" and a list of strings. Extract generously."""

zer0lint/cli.py

@@ -0,0 +1,182 @@
+"""CLI for zer0lint v0.2."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+from zer0lint import __version__
+from zer0lint.fixer import detect_extraction_model
+from zer0lint.orchestrator import run_check, run_generate
+
+console = Console()
+err_console = Console(stderr=True)
+
+app = typer.Typer(help="zer0lint — AI memory extraction diagnostics")
+
+DEFAULT_CONFIG_CANDIDATES = [
+    Path.home() / ".mem0" / "config.json",
+    Path.home() / ".mem0_config.json",
+    Path("config.json"),
+]
+
+
+def _load_config(config_path: Optional[str]) -> tuple[dict, Optional[Path]]:
+    """Load mem0 config from path or auto-detect. Returns (config_dict, resolved_path)."""
+    if config_path:
+        p = Path(config_path)
+        if not p.exists():
+            err_console.print(f"[red]Config not found:[/red] {p}")
+            raise typer.Exit(1)
+    else:
+        p = next((c for c in DEFAULT_CONFIG_CANDIDATES if c.exists()), None)
+        if not p:
+            err_console.print(
+                "[red]No config found.[/red] Provide with --config (e.g., --config ~/.mem0/config.json)"
+            )
+            raise typer.Exit(1)
+
+    try:
+        with open(p) as f:
+            return json.load(f), p
+    except Exception as e:
+        err_console.print(f"[red]Error reading config:[/red] {e}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def check(
+    config_path: Optional[str] = typer.Option(None, "--config", help="Path to mem0 config.json"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+    n: int = typer.Option(5, "--facts", "-n", help="Number of test facts"),
+) -> None:
+    """
+    Check your current mem0 extraction pipeline health.
+
+    Tests your config as-is with N synthetic domain facts.
+    Shows recall score and status (HEALTHY / ACCEPTABLE / DEGRADED / CRITICAL).
+    """
+    config_dict, resolved = _load_config(config_path)
+    model = detect_extraction_model(config_dict)
+    has_custom = bool(config_dict.get("custom_fact_extraction_prompt"))
+
+    console.print(f"\n[bold]zer0lint v{__version__} — extraction health check[/bold]")
+    console.print(f"Config : {resolved}")
+    console.print(f"Model  : {model}")
+    console.print(f"Prompt : {'custom' if has_custom else 'default (mem0 built-in)'}\n")
+
+    result = run_check(config_dict, verbose=verbose, n_facts=n)
+
+    color = {"HEALTHY": "green", "ACCEPTABLE": "cyan", "DEGRADED": "yellow", "CRITICAL": "red"}.get(
+        result["status"], "white"
+    )
+    console.print(
+        f"Score  : [bold {color}]{result['score']}/{result['total']} ({result['pct']:.0f}%) — {result['status']}[/bold {color}]\n"
+    )
+
+    if not verbose:
+        for d in result["details"]:
+            icon = "✅" if d["found"] else ("⚠ " if d.get("stored") else "❌")
+            console.print(f"  {icon} {d['label']}")
+
+    if result["status"] in ("DEGRADED", "CRITICAL"):
+        console.print(
+            "\n[yellow]Run [bold]zer0lint generate[/bold] to diagnose and fix.[/yellow]"
+        )
+    elif result["status"] == "ACCEPTABLE":
+        console.print("\n[cyan]Run [bold]zer0lint generate[/bold] to try improving to 5/5.[/cyan]")
+
+
+@app.command()
+def generate(
+    config_path: Optional[str] = typer.Option(None, "--config", help="Path to mem0 config.json"),
+    verbose: bool = typer.Option(True, "--verbose/--quiet", "-v/-q"),
+    apply: bool = typer.Option(True, "--apply/--dry-run", help="Apply fix to config"),
+    n: int = typer.Option(5, "--facts", "-n", help="Number of test facts"),
+) -> None:
+    """
+    Diagnose and fix your mem0 extraction pipeline.
+
+    Runs three phases:
+    1. Baseline recall test (current config)
+    2. Re-test with zer0lint technical extraction prompt (config-level)
+    3. If improved → write validated prompt to your config
+
+    Example:
+        zer0lint generate --config ~/.mem0/config.json
+        zer0lint generate --config ~/.mem0/config.json --dry-run
+    """
+    config_dict, resolved = _load_config(config_path)
+    model = detect_extraction_model(config_dict)
+    has_custom = bool(config_dict.get("custom_fact_extraction_prompt"))
+
+    console.print(f"\n[bold]zer0lint v{__version__} — extraction optimizer[/bold]")
+    console.print(f"Config : {resolved}")
+    console.print(f"Model  : {model}")
+    console.print(f"Prompt : {'custom' if has_custom else 'default (mem0 built-in)'}")
+    if not apply:
+        console.print("[yellow]Mode   : dry-run (will not write to config)[/yellow]")
+    console.print()
+
+    result = run_generate(
+        base_config=config_dict,
+        config_path=resolved if apply else None,
+        verbose=verbose,
+        n_facts=n,
+    )
+
+    if not result["success"]:
+        err_console.print("[red]✗ Generate failed.[/red]")
+        raise typer.Exit(1)
+
+    if result.get("verdict") == "already_healthy":
+        console.print("\n[green]✅ Your extraction is already at 100%. No changes needed.[/green]")
+        raise typer.Exit(0)
+
+    # Show before/after
+    init_pct = result.get("initial_pct", 0)
+    impr_pct = result.get("improved_pct", 0)
+    imp_pp = result.get("improvement_pp", 0)
+
+    console.print(f"\n[bold]Results:[/bold]")
+    console.print(f"  Before : {result['initial_score']}/{result.get('total', 5) if 'total' in result else 5} ({init_pct:.0f}%)")
+    console.print(f"  After  : {result['improved_score']}/{result.get('total', 5) if 'total' in result else 5} ({impr_pct:.0f}%)")
+    imp_color = "green" if imp_pp > 0 else "red"
+    console.print(f"  Δ      : [{imp_color}]{imp_pp:+.0f}pp[/{imp_color}]")
+
+    verdict = result.get("verdict")
+    if verdict == "improved" and result.get("applied"):
+        console.print(f"\n[green]✅ Fix applied to config.[/green]")
+        if result.get("backup_path"):
+            console.print(f"   Backup: {result['backup_path']}")
+        console.print("\n[dim]Restart your agent to pick up the new extraction prompt.[/dim]")
+    elif verdict == "improved" and not result.get("applied"):
+        console.print(f"\n[cyan]Would improve by {imp_pp:+.0f}pp — run without --dry-run to apply.[/cyan]")
+    elif verdict == "no_improvement":
+        console.print(f"\n[yellow]⚠ zer0lint prompt did not improve recall on this config.[/yellow]")
+        console.print("[dim]Your current setup may already be optimized, or a different domain prompt is needed.[/dim]")
+    elif verdict == "below_threshold":
+        console.print(f"\n[yellow]⚠ Improvement detected but below threshold — not applying automatically.[/yellow]")
+
+
+@app.callback(invoke_without_command=True)
+def version_cb(
+    show_version: bool = typer.Option(None, "--version", is_eager=True, help="Show version"),
+    ctx: typer.Context = typer.Context,
+) -> None:
+    """zer0lint — AI memory extraction diagnostics."""
+    if show_version:
+        console.print(f"zer0lint v{__version__}")
+        raise typer.Exit(0)
+
+
+if __name__ == "__main__":
+    app()

zer0lint/fixer.py

@@ -0,0 +1,116 @@
+"""Apply generated extraction prompts to mem0 config."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def backup_config(config_path: str | Path) -> str:
+    """
+    Backup the current config before modifying.
+
+    Args:
+        config_path: Path to mem0 config file
+
+    Returns:
+        Path to backup file
+    """
+    config_path = Path(config_path)
+    backup_path = config_path.parent / f"{config_path.stem}.backup.{datetime.now().isoformat()}"
+    shutil.copy2(config_path, backup_path)
+    return str(backup_path)
+
+
+def apply_prompt(
+    config_path: str | Path, new_prompt: str, backup: bool = True
+) -> dict:
+    """
+    Apply a new extraction prompt to mem0 config file.
+
+    Args:
+        config_path: Path to mem0 config.json
+        new_prompt: The new extraction prompt to set
+        backup: Whether to backup the original config (default True)
+
+    Returns:
+        Dict with keys: success (bool), backup_path (str), config_path (str), changes (dict)
+    """
+    config_path = Path(config_path)
+
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config not found: {config_path}")
+
+    # Read current config
+    with open(config_path) as f:
+        config = json.load(f)
+
+    # Backup
+    backup_path = None
+    if backup:
+        backup_path = backup_config(config_path)
+
+    # Record the old prompt for comparison
+    old_prompt = config.get("custom_fact_extraction_prompt", "(none)")
+
+    # Apply new prompt
+    config["custom_fact_extraction_prompt"] = new_prompt
+
+    # Write back
+    with open(config_path, "w") as f:
+        json.dump(config, f, indent=2)
+
+    return {
+        "success": True,
+        "config_path": str(config_path),
+        "backup_path": backup_path,
+        "changes": {
+            "field": "custom_fact_extraction_prompt",
+            "old_length": len(old_prompt),
+            "new_length": len(new_prompt),
+        },
+    }
+
+
+def detect_extraction_model(config: dict) -> str:
+    """
+    Detect which LLM is configured for extraction in mem0 config.
+
+    Args:
+        config: Parsed mem0 config dict
+
+    Returns:
+        String describing the extraction model (e.g., "mistral:7b", "gpt-4o", "unknown")
+    """
+    # Most configs have an llm.config.model field
+    llm_config = config.get("llm", {})
+    if isinstance(llm_config, dict):
+        if "config" in llm_config:
+            model = llm_config["config"].get("model")
+            if model:
+                return model
+        if "model" in llm_config:
+            return llm_config["model"]
+
+    return "unknown"
+
+
+def detect_vector_store(config: dict) -> str:
+    """
+    Detect which vector store is configured in mem0.
+
+    Args:
+        config: Parsed mem0 config dict
+
+    Returns:
+        String describing the vector store (e.g., "chroma", "qdrant", "unknown")
+    """
+    vs_config = config.get("vector_store", {})
+    if isinstance(vs_config, dict):
+        provider = vs_config.get("provider")
+        if provider:
+            return provider
+    return "unknown"

zer0lint/orchestrator.py

@@ -0,0 +1,240 @@
+"""Main orchestrator for zer0lint v0.2 — config-level injection, validated flow."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+from zer0lint.fixer import apply_prompt, detect_extraction_model
+from zer0lint.tester import (
+    generate_test_facts_for_categories,
+    validate_extraction_prompt,
+    cleanup_test_memories,
+    count_stored_memories,
+)
+
+
+# mem0's built-in default (personal assistant focused)
+MEM0_DEFAULT_PROMPT = """You are a Personal Information Organizer. Extract facts from conversations.
+Types: personal preferences, dates, relationships, activities, health, professional details.
+Return as JSON: {"facts": ["fact1", ...]}
+Input: Hi. Output: {"facts": []}"""
+
+# zer0lint's technical-domain prompt (validated: 5/5 recall vs 2/5 with personal prompt)
+TECHNICAL_EXTRACTION_PROMPT = """You are a Technical Memory Organizer for an AI agent workspace. Extract ALL factual statements from the input — technical decisions, infrastructure changes, product details, research findings, scores, dates, names, URLs, versions, and architectural choices.
+
+Types of information to extract:
+1. Infrastructure changes (services started/stopped, configs changed, versions installed)
+2. Technical decisions and their rationale
+3. Product/project details (names, versions, stars, URLs, status)
+4. Research findings and experiment results (scores, percentages, benchmarks)
+5. People, organizations, and relationships
+6. Dates, deadlines, and timelines
+7. File paths, port numbers, model names, and system specifics
+8. Security findings and audit scores
+9. Architecture patterns and design decisions
+10. Task assignments and status changes
+
+Examples:
+
+Input: We forked OpenClaw and installed it as v2026.3.14
+Output: {"facts": ["Forked OpenClaw, installed as version 2026.3.14"]}
+
+Input: The security audit scored 7.2 out of 10, up from 6.1
+Output: {"facts": ["Security audit score: 7.2/10", "Previous security audit score was 6.1"]}
+
+Input: Little Canary runs as HTTP server on port 18421 in full blocking mode
+Output: {"facts": ["Little Canary runs as HTTP server on port 18421", "Little Canary is in full blocking mode"]}
+
+Input: Hi, how are you?
+Output: {"facts": []}
+
+Return facts as JSON with key "facts" and a list of strings. Extract generously — it's better to capture too much than too little. Every concrete fact matters."""
+
+
+def _make_memory(base_config: dict, custom_prompt: Optional[str] = None, collection_suffix: str = "test"):
+    """Create a mem0 Memory instance with optional config-level prompt injection."""
+    from mem0 import Memory
+
+    config = json.loads(json.dumps(base_config))  # deep copy
+
+    # Swap collection to an isolated test namespace
+    if "vector_store" in config and "config" in config["vector_store"]:
+        orig_name = config["vector_store"]["config"].get("collection_name", "mem0")
+        config["vector_store"]["config"]["collection_name"] = f"{orig_name}_{collection_suffix}"
+
+    # Config-level prompt injection (the correct way in mem0 v1.x)
+    if custom_prompt:
+        config["custom_fact_extraction_prompt"] = custom_prompt
+    elif "custom_fact_extraction_prompt" in config:
+        del config["custom_fact_extraction_prompt"]
+
+    return Memory.from_config(config)
+
+
+def run_check(
+    base_config: dict,
+    verbose: bool = False,
+    n_facts: int = 5,
+) -> dict:
+    """
+    Phase 1: Baseline recall test.
+    Tests current config as-is against domain-relevant synthetic facts.
+
+    Returns dict: score, total, pct, status, details
+    """
+    if verbose:
+        model = detect_extraction_model(base_config)
+        print(f"[CHECK] Using model: {model}")
+        print(f"[CHECK] Testing with {n_facts} synthetic facts...")
+
+    memory = _make_memory(base_config, collection_suffix="check")
+    uid = "zer0lint_check"
+    cleanup_test_memories(memory, user_id=uid)
+
+    facts = generate_test_facts_for_categories(["technical", "research"], count=n_facts)
+    results = validate_extraction_prompt(memory, facts, "", user_id=uid, wait_seconds=1.5)
+
+    score = results["score"]
+    total = results["total"]
+    pct = score / total * 100 if total > 0 else 0
+
+    if pct >= 80:
+        status = "HEALTHY"
+    elif pct >= 60:
+        status = "ACCEPTABLE"
+    elif pct >= 40:
+        status = "DEGRADED"
+    else:
+        status = "CRITICAL"
+
+    if verbose:
+        print(f"[CHECK] Score: {score}/{total} ({pct:.0f}%) — {status}")
+        for d in results["details"]:
+            icon = "✅" if d["found"] else ("⚠ " if d.get("stored") else "❌")
+            print(f"  {icon} {d['label']}: {d['text'][:55]}...")
+
+    return {
+        "score": score,
+        "total": total,
+        "pct": pct,
+        "status": status,
+        "details": results["details"],
+        "failures": results["failures"],
+    }
+
+
+def run_generate(
+    base_config: dict,
+    config_path: Optional[str | Path] = None,
+    verbose: bool = False,
+    n_facts: int = 5,
+) -> dict:
+    """
+    Full zer0lint v0.2 generate flow (3 phases):
+      Phase 1: Baseline recall test (current config)
+      Phase 2: Re-test with zer0lint technical prompt (config-level injection)
+      Phase 3: If improved → write to config
+
+    Args:
+        base_config: Parsed mem0 config dict
+        config_path: Path to mem0 config.json (for applying the fix)
+        verbose: Print detailed output
+        n_facts: Number of test facts per run
+
+    Returns dict with: initial_score, improved_score, improvement_pp, applied, prompt, status
+    """
+    result = {
+        "success": False,
+        "initial_score": None,
+        "initial_pct": None,
+        "improved_score": None,
+        "improved_pct": None,
+        "improvement_pp": None,
+        "prompt": None,
+        "applied": False,
+        "backup_path": None,
+        "verdict": None,
+    }
+
+    facts = generate_test_facts_for_categories(["technical", "research"], count=n_facts)
+    uid_baseline = "zer0lint_baseline"
+    uid_improved = "zer0lint_improved"
+
+    # --- Phase 1: Baseline (current config, no changes) ---
+    if verbose:
+        print("\n[1/3] Baseline — testing current config as-is...")
+
+    mem_baseline = _make_memory(base_config, collection_suffix="baseline")
+    cleanup_test_memories(mem_baseline, user_id=uid_baseline)
+    res_baseline = validate_extraction_prompt(mem_baseline, facts, "", user_id=uid_baseline, wait_seconds=1.5)
+
+    initial_score = res_baseline["score"]
+    initial_pct = initial_score / n_facts * 100
+    result["initial_score"] = initial_score
+    result["initial_pct"] = initial_pct
+
+    if verbose:
+        print(f"  Baseline score: {initial_score}/{n_facts} ({initial_pct:.0f}%)")
+        for d in res_baseline["details"]:
+            icon = "✅" if d["found"] else "❌"
+            print(f"    {icon} {d['label']}")
+
+    # If already perfect, done
+    if initial_score >= n_facts:
+        if verbose:
+            print("\n✅ Extraction is already perfect. No changes needed.")
+        result["success"] = True
+        result["verdict"] = "already_healthy"
+        return result
+
+    # --- Phase 2: Re-test with zer0lint technical prompt (config-level) ---
+    if verbose:
+        print("\n[2/3] Re-testing with zer0lint technical extraction prompt (config-level)...")
+
+    mem_improved = _make_memory(base_config, custom_prompt=TECHNICAL_EXTRACTION_PROMPT, collection_suffix="improved")
+    cleanup_test_memories(mem_improved, user_id=uid_improved)
+    res_improved = validate_extraction_prompt(mem_improved, facts, "", user_id=uid_improved, wait_seconds=1.5)
+
+    improved_score = res_improved["score"]
+    improved_pct = improved_score / n_facts * 100
+    improvement_pp = improved_pct - initial_pct
+    result["improved_score"] = improved_score
+    result["improved_pct"] = improved_pct
+    result["improvement_pp"] = improvement_pp
+    result["prompt"] = TECHNICAL_EXTRACTION_PROMPT
+
+    if verbose:
+        print(f"  Improved score: {improved_score}/{n_facts} ({improved_pct:.0f}%)")
+        print(f"  Improvement: {improvement_pp:+.0f}pp")
+        for d in res_improved["details"]:
+            icon = "✅" if d["found"] else "❌"
+            print(f"    {icon} {d['label']}")
+
+    # --- Phase 3: Apply if improved and above threshold ---
+    if improvement_pp > 0 and improved_score >= max(initial_score, 4):
+        result["verdict"] = "improved"
+        if config_path:
+            if verbose:
+                print(f"\n[3/3] Applying fix to config ({initial_pct:.0f}% → {improved_pct:.0f}%)...")
+            apply_result = apply_prompt(config_path, TECHNICAL_EXTRACTION_PROMPT, backup=True)
+            result["applied"] = apply_result["success"]
+            result["backup_path"] = apply_result.get("backup_path")
+            if verbose:
+                print(f"  ✅ Config updated. Backup at: {apply_result.get('backup_path')}")
+        else:
+            if verbose:
+                print(f"\n[3/3] Would apply fix but no --config path given (dry run).")
+    elif improvement_pp <= 0:
+        result["verdict"] = "no_improvement"
+        if verbose:
+            print(f"\n⚠ Prompt did not improve score — not applying.")
+    else:
+        result["verdict"] = "below_threshold"
+        if verbose:
+            print(f"\n⚠ Score improved but still below threshold — not applying.")
+
+    result["success"] = True
+    return result