mesh-context-layer 0.4.0__py3-none-any.whl

mesh/__init__.py

@@ -0,0 +1,10 @@
+from .memory import Mesh
+from .io import export_namespace, import_namespace
+from .namespaces import list_namespaces, delete_namespace, rename_namespace, namespace_stats
+from .audit import log_recall, log_learn, get_audit_log, get_audit_stats
+from .context_builder import build_context
+from .digest import generate_digest
+from .passive import extract_memories_from_log
+
+__all__ = ["Mesh", "export_namespace", "import_namespace", "list_namespaces", "delete_namespace", "rename_namespace", "namespace_stats", "log_recall", "log_learn", "get_audit_log", "get_audit_stats", "build_context", "generate_digest", "extract_memories_from_log"]
+__version__ = "0.4.0"

mesh/audit.py

@@ -0,0 +1,189 @@
+"""
+mesh/audit.py — Audit trail for all memory reads and writes.
+Logs every recall() and learn() call with timestamp, agent, query/content, and result.
+"""
+
+import sqlite3
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+MESH_DIR = Path.home() / ".mesh"
+
+
+def _get_audit_db_path(namespace: str) -> Path:
+    return MESH_DIR / f"audit_{namespace}.db"
+
+
+def _init_audit_db(namespace: str):
+    db_path = _get_audit_db_path(namespace)
+    MESH_DIR.mkdir(exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    cursor = conn.cursor()
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS audit_log (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT NOT NULL,
+            action TEXT NOT NULL,           -- 'recall' or 'learn'
+            agent_id TEXT,
+            namespace TEXT,
+            query TEXT,                     -- for recalls: the query string
+            content TEXT,                   -- for learns: the content stored
+            top_result TEXT,                -- for recalls: the top result content
+            top_similarity REAL,            -- for recalls: top result similarity
+            result_count INTEGER,           -- for recalls: number of results
+            memory_id TEXT,                 -- for learns: the stored memory ID
+            had_conflict INTEGER DEFAULT 0  -- for learns: 1 if contradiction detected
+        )
+    """)
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_timestamp ON audit_log(timestamp)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_action ON audit_log(action)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_agent ON audit_log(agent_id)")
+    conn.commit()
+    conn.close()
+
+
+def log_recall(
+    query: str,
+    namespace: str,
+    agent_id: str,
+    results: list
+):
+    """Log a recall event to the audit trail."""
+    try:
+        _init_audit_db(namespace)
+        db_path = _get_audit_db_path(namespace)
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+        
+        top_result = results[0]["content"] if results else None
+        top_similarity = results[0].get("similarity", 0.0) if results else None
+        
+        cursor.execute("""
+            INSERT INTO audit_log 
+            (timestamp, action, agent_id, namespace, query, top_result, top_similarity, result_count)
+            VALUES (?, 'recall', ?, ?, ?, ?, ?, ?)
+        """, (
+            datetime.now(timezone.utc).isoformat(),
+            agent_id,
+            namespace,
+            query,
+            top_result,
+            top_similarity,
+            len(results)
+        ))
+        conn.commit()
+        conn.close()
+    except Exception:
+        pass  # Audit logging must never crash the main flow
+
+
+def log_learn(
+    content: str,
+    namespace: str,
+    agent_id: str,
+    result: dict
+):
+    """Log a learn event to the audit trail."""
+    try:
+        _init_audit_db(namespace)
+        db_path = _get_audit_db_path(namespace)
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            INSERT INTO audit_log 
+            (timestamp, action, agent_id, namespace, content, memory_id, had_conflict)
+            VALUES (?, 'learn', ?, ?, ?, ?, ?)
+        """, (
+            datetime.now(timezone.utc).isoformat(),
+            agent_id,
+            namespace,
+            content,
+            result.get("memory_id"),
+            1 if result.get("conflict") else 0
+        ))
+        conn.commit()
+        conn.close()
+    except Exception:
+        pass
+
+
+def get_audit_log(
+    namespace: str,
+    limit: int = 50,
+    action_filter: str = "all"
+) -> list[dict]:
+    """
+    Return recent audit entries for a namespace, most recent first.
+    
+    Args:
+        namespace: The namespace to query.
+        limit: Max entries to return.
+        action_filter: "all", "read" (maps to recall), or "write" (maps to learn).
+    """
+    db_path = _get_audit_db_path(namespace)
+    if not db_path.exists():
+        return []
+    
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    cursor = conn.cursor()
+    
+    action_map = {"read": "recall", "write": "learn"}
+    action_sql = action_map.get(action_filter)
+    
+    if action_sql:
+        cursor.execute("""
+            SELECT * FROM audit_log 
+            WHERE action = ?
+            ORDER BY timestamp DESC 
+            LIMIT ?
+        """, (action_sql, limit))
+    else:
+        cursor.execute("""
+            SELECT * FROM audit_log 
+            ORDER BY timestamp DESC 
+            LIMIT ?
+        """, (limit,))
+    
+    rows = cursor.fetchall()
+    conn.close()
+    return [dict(r) for r in rows]
+
+
+def get_audit_stats(namespace: str) -> dict:
+    """Return aggregate stats from the audit log."""
+    db_path = _get_audit_db_path(namespace)
+    if not db_path.exists():
+        return {"total_recalls": 0, "total_learns": 0, "agents": [], "conflicts_detected": 0}
+    
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    cursor = conn.cursor()
+    
+    cursor.execute("SELECT COUNT(*) as c FROM audit_log WHERE action = 'recall'")
+    recalls = cursor.fetchone()["c"]
+    
+    cursor.execute("SELECT COUNT(*) as c FROM audit_log WHERE action = 'learn'")
+    learns = cursor.fetchone()["c"]
+    
+    cursor.execute("SELECT DISTINCT agent_id FROM audit_log WHERE agent_id IS NOT NULL")
+    agents = [r["agent_id"] for r in cursor.fetchall()]
+    
+    cursor.execute("SELECT COUNT(*) as c FROM audit_log WHERE had_conflict = 1")
+    conflicts = cursor.fetchone()["c"]
+    
+    cursor.execute("SELECT MAX(timestamp) as last FROM audit_log")
+    last = cursor.fetchone()["last"]
+    
+    conn.close()
+    
+    return {
+        "total_recalls": recalls,
+        "total_learns": learns,
+        "agents": agents,
+        "conflicts_detected": conflicts,
+        "last_activity": last
+    }

mesh/cli.py

@@ -0,0 +1,321 @@
+"""
+mesh/cli.py — Command-line interface for Mesh.
+"""
+
+import sys
+import json
+import argparse
+
+
+def export_cmd():
+    """Entry point for: mesh-export"""
+    parser = argparse.ArgumentParser(
+        description="Export Mesh memories to a JSON file.",
+        epilog="Example: mesh-export backup.json --namespace work"
+    )
+    parser.add_argument("output", help="Output file path (e.g. backup.json)")
+    parser.add_argument("--namespace", default="shared", help="Namespace to export (default: shared)")
+    parser.add_argument("--no-embeddings", action="store_true",
+                        help="Exclude embedding vectors (smaller file, human-readable)")
+    args = parser.parse_args()
+
+    from .io import export_namespace
+    export_namespace(
+        namespace=args.namespace,
+        output_path=args.output,
+        include_embeddings=not args.no_embeddings
+    )
+
+
+def import_cmd():
+    """Entry point for: mesh-import"""
+    parser = argparse.ArgumentParser(
+        description="Import Mesh memories from a JSON export file.",
+        epilog="Example: mesh-import backup.json --namespace work"
+    )
+    parser.add_argument("input", help="Input export file path")
+    parser.add_argument("--namespace", default=None,
+                        help="Override target namespace (default: use namespace from export file)")
+    parser.add_argument("--overwrite", action="store_true",
+                        help="Overwrite existing memories with same ID (default: skip)")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Preview what would be imported without writing anything")
+    args = parser.parse_args()
+
+    from .io import import_namespace
+    import_namespace(
+        input_path=args.input,
+        target_namespace=args.namespace,
+        merge_strategy="overwrite" if args.overwrite else "skip_existing",
+        dry_run=args.dry_run
+    )
+
+
+def namespaces_cmd():
+    """Entry point for: mesh-namespaces"""
+    parser = argparse.ArgumentParser(
+        description="Manage Mesh namespaces.",
+        epilog="""Commands:
+  mesh-namespaces list                    List all namespaces
+  mesh-namespaces delete work             Delete namespace 'work' and all its memories
+  mesh-namespaces rename work work-old    Rename namespace 'work' to 'work-old'
+  mesh-namespaces stats work              Show stats for namespace 'work'
+        """
+    )
+    parser.add_argument("command", choices=["list", "delete", "rename", "stats"])
+    parser.add_argument("args", nargs="*", help="Arguments for the command")
+    parsed = parser.parse_args()
+
+    from .namespaces import list_namespaces, delete_namespace, rename_namespace, namespace_stats
+
+    if parsed.command == "list":
+        namespaces = list_namespaces()
+        if not namespaces:
+            print("No namespaces found.")
+            return
+        print(f"{'Namespace':<30} {'Memories':>10} {'Local-only':>12} {'Last updated':<25}")
+        print("-" * 80)
+        for ns in namespaces:
+            print(f"{ns['namespace']:<30} {ns['memory_count']:>10} {ns['local_only_count']:>12} {ns['last_updated']:<25}")
+
+    elif parsed.command == "delete":
+        if not parsed.args:
+            print("Error: provide a namespace name. Example: mesh-namespaces delete work")
+            sys.exit(1)
+        name = parsed.args[0]
+        confirm = input(f"Delete ALL memories in namespace '{name}'? This cannot be undone. [y/N] ")
+        if confirm.lower() != "y":
+            print("Cancelled.")
+            return
+        count = delete_namespace(name)
+        print(f"✓ Deleted namespace '{name}' ({count} memories removed)")
+
+    elif parsed.command == "rename":
+        if len(parsed.args) < 2:
+            print("Error: provide old and new names. Example: mesh-namespaces rename work work-archived")
+            sys.exit(1)
+        old, new = parsed.args[0], parsed.args[1]
+        count = rename_namespace(old, new)
+        print(f"✓ Renamed '{old}' → '{new}' ({count} memories updated)")
+
+    elif parsed.command == "stats":
+        if not parsed.args:
+            print("Error: provide a namespace name. Example: mesh-namespaces stats work")
+            sys.exit(1)
+        name = parsed.args[0]
+        stats = namespace_stats(name)
+        print(f"\nNamespace: {name}")
+        print(f"  Total memories:      {stats['memory_count']}")
+        print(f"  Local-only:          {stats['local_only_count']}")
+        print(f"  Exportable:          {stats['exportable_count']}")
+        print(f"  Memory types:        {json.dumps(stats['type_breakdown'], indent=4)}")
+        print(f"  Avg confidence:      {stats['avg_confidence']:.2f}")
+        print(f"  Stale memories:      {stats['stale_count']}")
+        print(f"  Total recalls:       {stats['total_recalls']}")
+        print(f"  Created:             {stats['oldest_memory']}")
+        print(f"  Last updated:        {stats['newest_memory']}")
+
+
+def context_cmd():
+    """Entry point for: mesh-context"""
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Output Mesh memories as a formatted system prompt block.",
+        epilog="""Examples:
+  mesh-context                              # Top 10 memories, markdown format
+  mesh-context --query "deploy process"     # Focused on deploy memories
+  mesh-context --format plain --count 5    # Plain text, 5 memories
+  CONTEXT=$(mesh-context) && echo $CONTEXT  # Capture for use in scripts
+
+Pipe directly into agent invocations:
+  aider --system-prompt "$(mesh-context)" ...
+  sgpt --system "$(mesh-context)" "help me with the deploy"
+        """
+    )
+    parser.add_argument("--query", default=None, help="Focus context on a specific topic")
+    parser.add_argument("--namespace", default=None, help="Namespace to query (default: shared)")
+    parser.add_argument("--count", type=int, default=10, help="Number of memories to include")
+    parser.add_argument("--format", choices=["markdown", "plain", "xml", "json"], default="markdown")
+    parser.add_argument("--min-confidence", type=float, default=0.3)
+    args = parser.parse_args()
+
+    from .context_builder import build_context
+    result = build_context(
+        query=args.query,
+        namespace=args.namespace,
+        count=args.count,
+        format=args.format,
+        min_confidence=args.min_confidence
+    )
+    if result:
+        print(result)
+    else:
+        import sys
+        print("No memories found.", file=sys.stderr)
+        sys.exit(1)
+
+
+def add_cmd():
+    """Entry point for: mesh-add"""
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Store a memory directly into Mesh.",
+        epilog="Example: mesh-add 'prod DB password rotated on May 1' --type fact --tags db,security"
+    )
+    parser.add_argument("content", help="The memory to store")
+    parser.add_argument("--type", dest="memory_type", default="general",
+                        choices=["fact", "process", "decision", "error", "general"],
+                        help="Memory type (default: general)")
+    parser.add_argument("--tags", default="", help="Comma-separated tags")
+    parser.add_argument("--private", action="store_true",
+                        help="Mark as local-only (never synced or exported)")
+    parser.add_argument("--namespace", default=None)
+    parser.add_argument("--confidence", type=float, default=1.0)
+    parser.add_argument("--ttl", type=int, default=None,
+                        help="Days before this memory is considered stale")
+    args = parser.parse_args()
+
+    from .memory import Mesh
+    import os
+    ns = args.namespace or os.environ.get("MESH_NAMESPACE", "shared")
+    mesh = Mesh(namespace=ns, agent_id="human-cli")
+    
+    tags = [t.strip() for t in args.tags.split(",") if t.strip()] if args.tags else []
+    
+    result = mesh.learn(
+        content=args.content,
+        memory_type=args.memory_type,
+        confidence=args.confidence,
+        tags=tags,
+        local_only=args.private,
+        ttl_days=args.ttl
+    )
+    
+    private_note = " (private — will not be exported or synced)" if args.private else ""
+    conflict_note = ""
+    if result.get("conflict"):
+        conflict_note = f"\n⚠️  Possible conflict with existing memory:\n   \"{result['conflict']['existing_memory']}\""
+    
+    print(f"✓ Stored [{args.memory_type}] in namespace '{ns}'{private_note}{conflict_note}")
+    if result.get("memory_id"):
+        print(f"  ID: {result['memory_id']}")
+
+
+def ask_cmd():
+    """Entry point for: mesh-ask"""
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Search Mesh for memories relevant to a question.",
+        epilog="Example: mesh-ask 'what is the deploy process?'"
+    )
+    parser.add_argument("query", help="What to search for")
+    parser.add_argument("--count", type=int, default=5)
+    parser.add_argument("--namespace", default=None)
+    parser.add_argument("--type", dest="memory_type", default=None)
+    parser.add_argument("--min-confidence", type=float, default=0.0)
+    args = parser.parse_args()
+
+    from .memory import Mesh
+    import os
+    ns = args.namespace or os.environ.get("MESH_NAMESPACE", "shared")
+    mesh = Mesh(namespace=ns, agent_id="human-cli")
+    
+    results = mesh.recall(
+        query=args.query,
+        count=args.count,
+        memory_type=args.memory_type,
+        min_confidence=args.min_confidence
+    )
+    
+    if not results:
+        print(f"No memories found for: {args.query}")
+        return
+    
+    print(f"\nFound {len(results)} memories in namespace '{ns}':\n")
+    for i, mem in enumerate(results, 1):
+        sim = mem.get("similarity", 0)
+        conf = mem.get("effective_confidence", mem.get("confidence", 1.0))
+        stale = " [STALE]" if mem.get("is_stale") else ""
+        private = " [PRIVATE]" if mem.get("local_only") else ""
+        tags = f" #{' #'.join(mem['tags'])}" if mem.get("tags") else ""
+        
+        print(f"  {i}. {mem['content']}{stale}{private}")
+        print(f"     type={mem.get('memory_type','general')} | "
+              f"similarity={sim:.2f} | confidence={conf:.2f} | "
+              f"from={mem.get('source_agent','unknown')}{tags}")
+        print()
+
+
+def why_cmd():
+    """Entry point for: mesh-why"""
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Show recent memory reads and writes across all agents (audit trail).",
+        epilog="Example: mesh-why --limit 30 --namespace work"
+    )
+    parser.add_argument("--limit", type=int, default=20)
+    parser.add_argument("--namespace", default=None)
+    parser.add_argument("--action", choices=["read", "write", "all"], default="all")
+    args = parser.parse_args()
+
+    from .audit import get_audit_log
+    import os
+    ns = args.namespace or os.environ.get("MESH_NAMESPACE", "shared")
+    entries = get_audit_log(namespace=ns, limit=args.limit, action_filter=args.action)
+    
+    if not entries:
+        print(f"No audit entries found for namespace '{ns}'.")
+        return
+    
+    print(f"\nAudit trail for namespace '{ns}' (most recent first):\n")
+    for entry in entries:
+        action_icon = "📖" if entry["action"] == "recall" else "✏️"
+        print(f"  {action_icon} [{entry['timestamp'][:19]}] {entry['agent_id']}")
+        if entry["action"] == "recall":
+            print(f"     asked: \"{entry['query']}\"")
+            if entry.get("top_result"):
+                print(f"     got:   \"{entry['top_result'][:80]}...\"" 
+                      if len(entry.get("top_result","")) > 80 
+                      else f"     got:   \"{entry['top_result']}\"")
+        else:
+            print(f"     stored: \"{entry['content'][:80]}\"")
+        print()
+
+
+def status_cmd():
+    """Entry point for: mesh-status"""
+    import argparse
+    parser = argparse.ArgumentParser(description="Show Mesh status overview.")
+    parser.add_argument("--namespace", default=None)
+    args = parser.parse_args()
+
+    from .namespaces import list_namespaces, namespace_stats
+    from .audit import get_audit_log
+    import os
+
+    ns = args.namespace or os.environ.get("MESH_NAMESPACE", "shared")
+    
+    try:
+        stats = namespace_stats(ns)
+    except ValueError:
+        print(f"Namespace '{ns}' is empty or does not exist yet.")
+        print(f"Run 'mesh-add \"something\"' to create it.")
+        return
+    
+    recent = get_audit_log(namespace=ns, limit=5)
+    last_activity = recent[0]["timestamp"][:19] if recent else "never"
+    
+    print(f"\nMesh Status — namespace: {ns}\n")
+    print(f"  Memories:       {stats['memory_count']} total, "
+          f"{stats['local_only_count']} private, "
+          f"{stats['stale_count']} stale")
+    print(f"  Exportable:     {stats['exportable_count']}")
+    print(f"  Total recalls:  {stats['total_recalls']}")
+    print(f"  Last activity:  {last_activity}")
+    print(f"  Types:          {stats['type_breakdown']}")
+    
+    all_ns = list_namespaces()
+    if len(all_ns) > 1:
+        others = [n["namespace"] for n in all_ns if n["namespace"] != ns]
+        print(f"  Other namespaces: {', '.join(others)}")
+    print()

mesh/context_builder.py

@@ -0,0 +1,96 @@
+"""
+mesh/context_builder.py — Builds formatted system prompt context blocks from Mesh memories.
+"""
+
+import os
+from typing import Optional
+from .memory import Mesh
+
+
+def build_context(
+    query: Optional[str] = None,
+    namespace: Optional[str] = None,
+    count: int = 10,
+    format: str = "markdown",
+    min_confidence: float = 0.3,
+    agent_id: str = "context-builder"
+) -> str:
+    """
+    Build a formatted context block from the most relevant memories.
+    
+    Args:
+        query: Optional query to focus the context. If None, pulls top memories by access frequency.
+        namespace: Namespace to query. Defaults to MESH_NAMESPACE env var or "shared".
+        count: Number of memories to include. Default 10.
+        format: Output format — "markdown", "plain", "xml", or "json".
+        min_confidence: Minimum confidence score to include. Default 0.3.
+        agent_id: Agent ID to log this context pull under.
+    
+    Returns:
+        Formatted string ready to paste into a system prompt.
+    """
+    ns = namespace or os.environ.get("MESH_NAMESPACE", "shared")
+    mesh = Mesh(namespace=ns, agent_id=agent_id)
+    
+    if query:
+        memories = mesh.recall(query=query, n=count, min_confidence=min_confidence)
+    else:
+        # No query: pull most-accessed memories as general context
+        memories = mesh.inspect(limit=count * 3)  # get more, then sort
+        memories = sorted(memories, key=lambda m: m.get("access_count", 0), reverse=True)
+        memories = [m for m in memories if m.get("confidence", 1.0) >= min_confidence][:count]
+    
+    if not memories:
+        return ""
+    
+    return _format(memories, format, ns)
+
+
+def _format(memories: list, format: str, namespace: str) -> str:
+    if format == "json":
+        import json
+        return json.dumps({
+            "mesh_context": True,
+            "namespace": namespace,
+            "memories": memories
+        }, indent=2)
+    
+    if format == "xml":
+        lines = ["<mesh_context>"]
+        for mem in memories:
+            stale = ' stale="true"' if mem.get("is_stale") else ""
+            lines.append(f'  <memory type="{mem.get("memory_type", "general")}"{stale}>')
+            lines.append(f'    {mem["content"]}')
+            lines.append(f'  </memory>')
+        lines.append("</mesh_context>")
+        return "\n".join(lines)
+    
+    if format == "plain":
+        lines = ["[MESH CONTEXT]"]
+        for mem in memories:
+            stale = " (possibly stale)" if mem.get("is_stale") else ""
+            lines.append(f"- {mem['content']}{stale}")
+        return "\n".join(lines)
+    
+    # Default: markdown (best for LLM system prompts)
+    lines = [
+        "<mesh_context>",
+        "The following facts were stored by AI agents working on this project.",
+        "Trust these as ground truth unless you have newer information.",
+        "",
+    ]
+    
+    by_type: dict = {}
+    for mem in memories:
+        t = mem.get("memory_type", "general")
+        by_type.setdefault(t, []).append(mem)
+    
+    for mem_type, mems in sorted(by_type.items()):
+        lines.append(f"**{mem_type.title()}**")
+        for mem in mems:
+            stale = " *(possibly stale)*" if mem.get("is_stale") else ""
+            lines.append(f"- {mem['content']}{stale}")
+        lines.append("")
+    
+    lines.append("</mesh_context>")
+    return "\n".join(lines)