mnemo-dev 0.1.0__py3-none-any.whl

mnemo/clients.py

@@ -0,0 +1,147 @@
+"""AI client configuration targets for Mnemo."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ClientTarget:
+    """Configuration and context-file locations for an MCP client."""
+
+    key: str
+    display_name: str
+    mcp_config_path: Path | None
+    context_file: str | None
+    context_label: str
+
+
+CLIENTS: dict[str, ClientTarget] = {
+    "amazonq": ClientTarget(
+        key="amazonq",
+        display_name="Amazon Q",
+        mcp_config_path=Path.home() / ".aws" / "amazonq" / "mcp.json",
+        context_file=".amazonq/rules/mnemo.md",
+        context_label="rule",
+    ),
+    "cursor": ClientTarget(
+        key="cursor",
+        display_name="Cursor",
+        mcp_config_path=Path.home() / ".cursor" / "mcp.json",
+        context_file=".cursorrules",
+        context_label="rules file",
+    ),
+    "claude-code": ClientTarget(
+        key="claude-code",
+        display_name="Claude Code",
+        mcp_config_path=Path.home() / ".claude" / "mcp.json",
+        context_file="CLAUDE.md",
+        context_label="project instructions",
+    ),
+    "kiro": ClientTarget(
+        key="kiro",
+        display_name="Kiro",
+        mcp_config_path=Path.home() / ".kiro" / "mcp.json",
+        context_file=".kiro/rules/mnemo.md",
+        context_label="rule",
+    ),
+    "copilot": ClientTarget(
+        key="copilot",
+        display_name="GitHub Copilot",
+        mcp_config_path=Path.home() / ".config" / "github-copilot" / "mcp.json",
+        context_file=".github/copilot-instructions.md",
+        context_label="instructions",
+    ),
+    "generic": ClientTarget(
+        key="generic",
+        display_name="Generic MCP Client",
+        mcp_config_path=None,
+        context_file="MNEMO.md",
+        context_label="instructions",
+    ),
+}
+
+DEFAULT_CLIENT = "amazonq"
+CLIENT_CHOICES = tuple(CLIENTS.keys()) + ("all",)
+
+
+def resolve_clients(selection: str) -> list[ClientTarget]:
+    """Resolve a CLI client selection into concrete client targets."""
+    normalized = selection.lower().strip()
+    if normalized == "all":
+        return list(CLIENTS.values())
+    try:
+        return [CLIENTS[normalized]]
+    except KeyError as exc:
+        valid = ", ".join(CLIENT_CHOICES)
+        raise ValueError(f"Unknown client '{selection}'. Choose one of: {valid}") from exc
+
+
+def find_mnemo_mcp_command() -> str:
+    """Find the installed mnemo-mcp executable, falling back to PATH lookup by name."""
+    if getattr(sys, "frozen", False):
+        return str(Path(sys.executable))
+
+    mnemo_bin = shutil.which("mnemo-mcp")
+    if mnemo_bin:
+        return mnemo_bin
+
+    executable_name = "mnemo-mcp.exe" if sys.platform.startswith("win") else "mnemo-mcp"
+    candidates = [
+        Path(sys.prefix) / "Scripts" / executable_name,
+        Path(sys.prefix) / "bin" / executable_name,
+        Path.home() / ".local" / "bin" / executable_name,
+        Path.home() / "Library" / "Python" / "3.12" / "bin" / executable_name,
+        Path.home() / "Library" / "Python" / "3.11" / "bin" / executable_name,
+        Path.home() / "AppData" / "Roaming" / "Python" / "Python312" / "Scripts" / executable_name,
+        Path.home() / "AppData" / "Roaming" / "Python" / "Python311" / "Scripts" / executable_name,
+        Path.home() / "AppData" / "Roaming" / "Python" / "Python310" / "Scripts" / executable_name,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return str(candidate)
+    return "mnemo-mcp"
+
+
+def setup_mcp_config(target: ClientTarget, command: str | None = None) -> bool:
+    """Register Mnemo in a client's MCP config.
+
+    Returns True when the config file changed.
+    """
+    if target.mcp_config_path is None:
+        return False
+
+    config_path = target.mcp_config_path
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    config = {}
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            config = {}
+
+    config.setdefault("mcpServers", {})
+    server = {
+        "command": command or find_mnemo_mcp_command(),
+        "args": [],
+        "env": {},
+    }
+
+    if config["mcpServers"].get("mnemo") == server:
+        return False
+
+    config["mcpServers"]["mnemo"] = server
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+def context_path(repo_root: Path, target: ClientTarget) -> Path | None:
+    """Return the repo-local context file path for a client."""
+    if not target.context_file:
+        return None
+    return repo_root / target.context_file

mnemo/code_review/__init__.py

@@ -0,0 +1,68 @@
+"""Code review context - store PR summaries, feedback, and rejected suggestions."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..storage import Collections, get_storage
+
+
+def _load_reviews(repo_root: Path) -> list[dict]:
+    data = get_storage(repo_root).read_collection(Collections.REVIEWS)
+    return data if isinstance(data, list) else []
+
+
+def _save_reviews(repo_root: Path, reviews: list[dict]) -> None:
+    get_storage(repo_root).write_collection(Collections.REVIEWS, reviews[-100:])
+
+
+def add_review(
+    repo_root: Path,
+    summary: str,
+    files: list[str] | None = None,
+    feedback: str = "",
+    outcome: str = "approved",
+) -> dict:
+    """Store a code review summary."""
+    reviews = _load_reviews(repo_root)
+    entry = {
+        "id": len(reviews) + 1,
+        "timestamp": time.time(),
+        "summary": summary,
+        "files": files or [],
+        "feedback": feedback,
+        "outcome": outcome,
+    }
+    reviews.append(entry)
+    _save_reviews(repo_root, reviews)
+    return entry
+
+
+def get_reviews_for_file(repo_root: Path, filepath: str) -> list[dict]:
+    """Get all review feedback related to a specific file."""
+    reviews = _load_reviews(repo_root)
+    return [review for review in reviews if filepath in (review.get("files") or [])]
+
+
+def get_rejected_suggestions(repo_root: Path) -> list[dict]:
+    """Get suggestions that were rejected so assistants should not repeat them."""
+    reviews = _load_reviews(repo_root)
+    return [review for review in reviews if review.get("outcome") == "rejected"]
+
+
+def format_reviews(repo_root: Path) -> str:
+    """Format review history as markdown."""
+    reviews = _load_reviews(repo_root)
+    if not reviews:
+        return "No code review history stored."
+
+    lines = ["# Code Review History\n"]
+    for review in reviews[-20:]:
+        status = f"[{review['outcome']}]" if review.get("outcome") else ""
+        lines.append(f"- {review['summary']} {status}")
+        if review.get("feedback"):
+            lines.append(f"  Feedback: {review['feedback']}")
+        if review.get("files"):
+            lines.append(f"  Files: {', '.join(review['files'])}")
+    return "\n".join(lines)

mnemo/config.py

@@ -0,0 +1,30 @@
+"""Mnemo configuration and constants."""
+
+from pathlib import Path
+
+MNEMO_DIR = ".mnemo"
+MEMORY_FILE = "memory.json"
+REPO_MAP_FILE = "repo_map.json"
+DECISIONS_FILE = "decisions.json"
+CONTEXT_FILE = "context.json"
+
+SUPPORTED_EXTENSIONS = {
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".jsx": "javascript",
+    ".go": "go",
+    ".cs": "csharp",
+}
+
+IGNORE_DIRS = {
+    "node_modules", ".git", "__pycache__", ".venv", "venv",
+    "dist", "build", ".mnemo", ".tox", ".mypy_cache", "egg-info",
+    "bin", "obj", "packages", ".vs",
+    "wwwroot", "publish", "artifacts", "TestResults",
+}
+
+
+def mnemo_path(repo_root: Path) -> Path:
+    return repo_root / MNEMO_DIR

mnemo/dependency_graph/__init__.py

@@ -0,0 +1,126 @@
+"""Dependency Graph — map service-to-service relationships and impact analysis."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from ..config import IGNORE_DIRS, mnemo_path
+
+
+def _should_ignore(path: Path) -> bool:
+    return any(part in IGNORE_DIRS for part in path.parts)
+
+
+def build_dependency_graph(repo_root: Path) -> dict[str, dict]:
+    """Build a graph of service dependencies from code analysis."""
+    graph: dict[str, dict] = {}
+
+    # Detect services (top-level directories with Program.cs or .csproj)
+    services = set()
+    for f in repo_root.rglob("Program.cs"):
+        if not _should_ignore(f):
+            services.add(f.relative_to(repo_root).parts[0])
+    for f in repo_root.rglob("*.csproj"):
+        if not _should_ignore(f):
+            services.add(f.relative_to(repo_root).parts[0])
+
+    for service in services:
+        svc_path = repo_root / service
+        graph[service] = {"calls": [], "called_by": [], "packages": [], "internal_deps": []}
+
+        for cs_file in svc_path.rglob("*.cs"):
+            if _should_ignore(cs_file):
+                continue
+            try:
+                content = cs_file.read_text(errors="replace")
+            except (OSError, PermissionError):
+                continue
+
+            # Detect HTTP calls to other services
+            for other_svc in services:
+                if other_svc == service:
+                    continue
+                if other_svc.lower() in content.lower():
+                    if other_svc not in graph[service]["calls"]:
+                        graph[service]["calls"].append(other_svc)
+
+            # Detect project references
+            refs = re.findall(r'using\s+([\w.]+Service)', content)
+            for ref in refs:
+                if ref not in graph[service]["internal_deps"]:
+                    graph[service]["internal_deps"].append(ref)
+
+        # Parse .csproj for package deps
+        for csproj in svc_path.rglob("*.csproj"):
+            if _should_ignore(csproj):
+                continue
+            try:
+                content = csproj.read_text(errors="replace")
+                packages = re.findall(r'<PackageReference\s+Include="([^"]+)"', content)
+                graph[service]["packages"] = packages
+            except (OSError, PermissionError):
+                pass
+
+    # Build reverse graph (called_by)
+    for svc, info in graph.items():
+        for target in info["calls"]:
+            if target in graph:
+                if svc not in graph[target]["called_by"]:
+                    graph[target]["called_by"].append(svc)
+
+    return graph
+
+
+def impact_analysis(repo_root: Path, service_or_file: str) -> str:
+    """Answer: what breaks if I change this?"""
+    graph = build_dependency_graph(repo_root)
+    query = service_or_file.lower()
+
+    # Find matching service
+    target_svc = None
+    for svc in graph:
+        if query in svc.lower():
+            target_svc = svc
+            break
+
+    if not target_svc:
+        return f"No service matching '{service_or_file}' found."
+
+    info = graph[target_svc]
+    lines = [f"# Impact Analysis: {target_svc}\n"]
+
+    if info["called_by"]:
+        lines.append("## Services that depend on this (will break if you change the API):")
+        for dep in info["called_by"]:
+            lines.append(f"- **{dep}**")
+        lines.append("")
+
+    if info["calls"]:
+        lines.append("## Services this depends on:")
+        for dep in info["calls"]:
+            lines.append(f"- {dep}")
+        lines.append("")
+
+    if not info["called_by"] and not info["calls"]:
+        lines.append("No known dependencies. This service appears isolated.")
+
+    return "\n".join(lines)
+
+
+def format_graph(repo_root: Path) -> str:
+    """Format the full dependency graph as markdown."""
+    graph = build_dependency_graph(repo_root)
+    if not graph:
+        return "No services detected."
+
+    lines = ["# Dependency Graph\n"]
+    for svc in sorted(graph.keys()):
+        info = graph[svc]
+        calls = f" → {', '.join(info['calls'])}" if info["calls"] else ""
+        called_by = f" ← {', '.join(info['called_by'])}" if info["called_by"] else ""
+        lines.append(f"**{svc}**{calls}{called_by}")
+        if info["packages"]:
+            lines.append(f"  Packages: {', '.join(info['packages'][:5])}")
+    return "\n".join(lines)

mnemo/doctor.py

@@ -0,0 +1,118 @@
+"""Installation and setup diagnostics for Mnemo."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from importlib.metadata import PackageNotFoundError, version
+
+from .clients import DEFAULT_CLIENT, ClientTarget, context_path, find_mnemo_mcp_command, resolve_clients
+from .config import mnemo_path
+
+
+def _status(ok: bool) -> str:
+    return "OK" if ok else "WARN"
+
+
+def _check_mcp_config(target: ClientTarget) -> tuple[bool, str]:
+    if target.mcp_config_path is None:
+        return True, "manual MCP config required"
+    if not target.mcp_config_path.exists():
+        return False, f"missing {target.mcp_config_path}"
+    try:
+        config = json.loads(target.mcp_config_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return False, f"invalid JSON in {target.mcp_config_path}"
+    if "mnemo" not in config.get("mcpServers", {}):
+        return False, f"mnemo server not registered in {target.mcp_config_path}"
+    return True, str(target.mcp_config_path)
+
+
+def _check_mcp_alive(command: str) -> bool:
+    """Send a ping to the MCP server to check if it responds."""
+    init_msg = json.dumps({
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "doctor"}}
+    })
+    try:
+        result = subprocess.run(
+            [command, "mcp"] if command != "mnemo-mcp" else [command],
+            input=init_msg, capture_output=True, text=True, timeout=5,
+        )
+        return '"serverInfo"' in result.stdout
+    except Exception:
+        return False
+
+
+def _check_context_file(repo_root: Path, target: ClientTarget) -> tuple[bool, str]:
+    path = context_path(repo_root, target)
+    if path is None:
+        return True, "no context file required"
+    if path.exists():
+        return True, str(path.relative_to(repo_root))
+    return False, f"missing {path.relative_to(repo_root)}"
+
+
+def doctor(repo_root: Path, client: str = DEFAULT_CLIENT) -> str:
+    """Return a human-readable setup diagnostic report."""
+    targets = resolve_clients(client)
+    lines = ["# Mnemo Doctor", ""]
+
+    python_ok = sys.version_info >= (3, 10)
+    lines.append(f"[{_status(python_ok)}] Python: {sys.version.split()[0]} (requires 3.10+)")
+    lines.append(f"[OK] Runtime mode: {'binary' if getattr(sys, 'frozen', False) else 'python-package'}")
+
+    try:
+        package_version = version("mnemo")
+        lines.append(f"[OK] Mnemo package: {package_version}")
+    except PackageNotFoundError:
+        lines.append("[WARN] Mnemo package: not installed as a package")
+
+    try:
+        import chromadb
+        lines.append(f"[OK] Semantic search: chromadb {chromadb.__version__}")
+    except ImportError:
+        lines.append("[OK] Semantic search: keyword fallback (chromadb will auto-install on first use)")
+
+    command = find_mnemo_mcp_command()
+    command_ok = command != "mnemo-mcp"
+    lines.append(f"[{_status(command_ok)}] mnemo-mcp command: {command}")
+
+    # Live MCP server check
+    mcp_alive = _check_mcp_alive(command)
+    lines.append(f"[{_status(mcp_alive)}] MCP server responds: {'yes' if mcp_alive else 'no — restart your IDE'}")
+
+    base = mnemo_path(repo_root)
+    initialized = base.exists()
+    lines.append(f"[{_status(initialized)}] Repository initialized: {base}")
+
+    if initialized:
+        for filename in ("context.json", "memory.json", "decisions.json", "hashes.json"):
+            path = base / filename
+            exists = path.exists()
+            lines.append(f"[{_status(exists)}] {filename}: {path}")
+
+    lines.append("")
+    lines.append("## Client Setup")
+    for target in targets:
+        context_ok, context_message = _check_context_file(repo_root, target)
+        config_ok, config_message = _check_mcp_config(target)
+        lines.append(f"[{_status(context_ok)}] {target.display_name} context: {context_message}")
+        lines.append(f"[{_status(config_ok)}] {target.display_name} MCP config: {config_message}")
+
+    if not initialized:
+        lines.append("")
+        lines.append("Run `mnemo init` in this repository.")
+    else:
+        missing_clients = [
+            target.display_name
+            for target in targets
+            if not _check_context_file(repo_root, target)[0] or not _check_mcp_config(target)[0]
+        ]
+        if missing_clients:
+            lines.append("")
+            lines.append(f"Run `mnemo init --client {client}` to repair missing client setup.")
+
+    return "\n".join(lines)

mnemo/embeddings/__init__.py

@@ -0,0 +1,47 @@
+"""Embedding provider abstractions for local semantic retrieval."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+import re
+from typing import Protocol
+
+
+def _tokenize(text: str) -> list[str]:
+    normalized = text.lower().replace("_", " ")
+    return re.findall(r"[a-zA-Z0-9]+", normalized)
+
+
+@dataclass(frozen=True)
+class SparseEmbedding:
+    """Lightweight token-count embedding used for fallback retrieval."""
+
+    counts: dict[str, int]
+
+    def score(self, other: "SparseEmbedding") -> float:
+        if not self.counts or not other.counts:
+            return 0.0
+        overlap = sum(min(self.counts.get(tok, 0), other.counts.get(tok, 0)) for tok in self.counts)
+        norm = max(sum(self.counts.values()), 1)
+        return overlap / norm
+
+
+class EmbeddingProvider(Protocol):
+    """Embedding provider protocol."""
+
+    def embed(self, text: str) -> SparseEmbedding:
+        ...
+
+    def embed_many(self, texts: list[str]) -> list[SparseEmbedding]:
+        ...
+
+
+class KeywordEmbeddingProvider:
+    """Cheap keyword provider used as default and in tests."""
+
+    def embed(self, text: str) -> SparseEmbedding:
+        return SparseEmbedding(dict(Counter(_tokenize(text))))
+
+    def embed_many(self, texts: list[str]) -> list[SparseEmbedding]:
+        return [self.embed(text) for text in texts]

mnemo/errors/__init__.py

@@ -0,0 +1,81 @@
+"""Error memory - store error, cause, and fix mappings for instant recall."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..storage import Collections, get_storage
+
+
+def _load_errors(repo_root: Path) -> list[dict]:
+    data = get_storage(repo_root).read_collection(Collections.ERRORS)
+    return data if isinstance(data, list) else []
+
+
+def _save_errors(repo_root: Path, errors: list[dict]) -> None:
+    get_storage(repo_root).write_collection(Collections.ERRORS, errors[-200:])
+
+
+def add_error(
+    repo_root: Path,
+    error: str,
+    cause: str,
+    fix: str,
+    file: str = "",
+    tags: list[str] | None = None,
+) -> dict:
+    """Store an error, cause, and fix mapping."""
+    errors = _load_errors(repo_root)
+    entry = {
+        "id": len(errors) + 1,
+        "timestamp": time.time(),
+        "error": error,
+        "cause": cause,
+        "fix": fix,
+        "file": file,
+        "tags": tags or [],
+    }
+    errors.append(entry)
+    _save_errors(repo_root, errors)
+    return entry
+
+
+def search_errors(repo_root: Path, query: str) -> str:
+    """Search error memory for matching errors."""
+    errors = _load_errors(repo_root)
+    query_lower = query.lower()
+
+    matches = [
+        error
+        for error in errors
+        if query_lower in error["error"].lower()
+        or query_lower in error.get("cause", "").lower()
+        or query_lower in error.get("file", "").lower()
+        or any(query_lower in tag.lower() for tag in error.get("tags", []))
+    ]
+
+    if not matches:
+        return f"No known errors matching '{query}'."
+
+    lines = [f"# Known Errors matching '{query}'\n"]
+    for error in matches[-10:]:
+        lines.append(f"## {error['error']}")
+        lines.append(f"**Cause:** {error['cause']}")
+        lines.append(f"**Fix:** {error['fix']}")
+        if error.get("file"):
+            lines.append(f"**File:** {error['file']}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def format_errors(repo_root: Path) -> str:
+    """Format all stored errors as markdown."""
+    errors = _load_errors(repo_root)
+    if not errors:
+        return "No errors stored."
+
+    lines = ["# Error Memory\n"]
+    for error in errors[-20:]:
+        lines.append(f"- **{error['error']}** -> {error['fix']}")
+    return "\n".join(lines)