claude-memory-agent 2.0.1 → 2.2.0

package/mcp_server.py

@@ -0,0 +1,451 @@
+"""MCP stdio server for Claude Memory.
+
+Thin adapter that exposes the memory system's core skills as MCP tools,
+allowing any MCP-compatible client (OpenClaw, Claude Code, etc.) to
+store, search, and manage memories over stdio JSON-RPC.
+
+Usage:
+    python mcp_server.py              # stdio mode (default)
+    mcp dev mcp_server.py             # interactive inspector
+
+Shares the same SQLite database as the HTTP server (main.py) via WAL mode.
+"""
+
+# ── CRITICAL: Suppress stdout noise before ANY library imports ──────────
+# stdout is reserved exclusively for MCP JSON-RPC protocol messages.
+# Any stray print/progress-bar on stdout will corrupt the protocol.
+
+import os
+import sys
+
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+os.environ.setdefault("TRANSFORMERS_NO_ADVISORY_WARNINGS", "1")
+os.environ.setdefault("TQDM_DISABLE", "1")
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+import logging
+
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+)
+logger = logging.getLogger("mcp-claude-memory")
+
+# Add memory-agent/ to sys.path so local imports (services.*, skills.*, config) resolve
+AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
+if AGENT_DIR not in sys.path:
+    sys.path.insert(0, AGENT_DIR)
+
+# ── Imports ─────────────────────────────────────────────────────────────
+
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+# MCP SDK - support both v1 (FastMCP) and v2 (MCPServer) import paths
+try:
+    from mcp.server.fastmcp import FastMCP, Context
+except ImportError:
+    try:
+        from mcp.server.mcpserver import MCPServer as FastMCP, Context
+    except ImportError:
+        raise ImportError(
+            "MCP SDK not found. Install with: pip install 'mcp>=1.0.0'"
+        )
+
+from services.database import DatabaseService
+from services.embeddings import EmbeddingService
+from config import config
+
+# Direct skill imports - no HTTP, no FastAPI dependency
+from skills.store import store_memory, store_project, store_pattern
+from skills.search import semantic_search, search_patterns, get_project_context
+
+
+# ── Lifespan: DB + Embeddings initialization ───────────────────────────
+
+@dataclass
+class AppContext:
+    db: DatabaseService
+    embeddings: EmbeddingService
+
+
+@asynccontextmanager
+async def app_lifespan(server: Any) -> AsyncIterator[AppContext]:
+    """Initialize database and embedding services on startup, clean up on shutdown."""
+    logger.info("Initializing Claude Memory MCP server...")
+
+    db = DatabaseService()
+    await db.connect()
+    await db.initialize_schema()
+    logger.info(f"Database connected: {db.db_path}")
+
+    logger.info(
+        f"Loading embedding model: {config.EMBEDDING_MODEL} "
+        f"(provider: {config.EMBEDDING_PROVIDER}) - this may take a moment..."
+    )
+    embeddings = EmbeddingService(
+        provider_type=config.EMBEDDING_PROVIDER,
+        model=config.EMBEDDING_MODEL,
+    )
+    logger.info(f"Embeddings ready (dim={embeddings.get_dimension()})")
+
+    try:
+        yield AppContext(db=db, embeddings=embeddings)
+    finally:
+        if db.conn:
+            db.conn.close()
+        logger.info("Claude Memory MCP server shut down.")
+
+
+# ── MCP Server ──────────────────────────────────────────────────────────
+
+mcp_server = FastMCP("claude-memory", lifespan=app_lifespan)
+
+
+def _get_app(ctx: Context) -> AppContext:
+    """Extract AppContext from the MCP request context."""
+    return ctx.request_context.lifespan_context
+
+
+# ── Tools ───────────────────────────────────────────────────────────────
+
+@mcp_server.tool()
+async def memory_store(
+    ctx: Context,
+    content: str,
+    memory_type: str = "chunk",
+    tags: Optional[List[str]] = None,
+    importance: int = 5,
+    outcome: Optional[str] = None,
+    success: Optional[bool] = None,
+    project_path: Optional[str] = None,
+    project_name: Optional[str] = None,
+    project_type: Optional[str] = None,
+    tech_stack: Optional[List[str]] = None,
+    agent_type: Optional[str] = None,
+) -> str:
+    """Store a memory with semantic embedding.
+
+    Args:
+        content: Content to remember
+        memory_type: Type: session, decision, code, chunk, error, preference
+        tags: Classification tags
+        importance: 1-10 importance scale (default 5)
+        outcome: What happened
+        success: Did it work?
+        project_path: Project path
+        project_name: Project name
+        project_type: Project type (wordpress, react, etc.)
+        tech_stack: Technologies used
+        agent_type: Agent used (Explore, Plan, etc.)
+    """
+    app = _get_app(ctx)
+    result = await store_memory(
+        db=app.db,
+        embeddings=app.embeddings,
+        content=content,
+        memory_type=memory_type,
+        tags=tags,
+        importance=importance,
+        outcome=outcome,
+        success=success,
+        project_path=project_path,
+        project_name=project_name,
+        project_type=project_type,
+        tech_stack=tech_stack,
+        agent_type=agent_type,
+    )
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_search(
+    ctx: Context,
+    query: str,
+    limit: int = 10,
+    memory_type: Optional[str] = None,
+    project_path: Optional[str] = None,
+    success_only: bool = False,
+    threshold: float = 0.5,
+) -> str:
+    """Search memories using natural language. Returns similar content ranked by relevance.
+
+    Args:
+        query: Search query
+        limit: Max results (default 10)
+        memory_type: Filter: session, decision, code, chunk, error, preference
+        project_path: Filter by project
+        success_only: Only return successful memories
+        threshold: Minimum similarity 0-1 (default 0.5)
+    """
+    app = _get_app(ctx)
+    result = await semantic_search(
+        db=app.db,
+        embeddings=app.embeddings,
+        query=query,
+        limit=limit,
+        memory_type=memory_type,
+        project_path=project_path,
+        success_only=success_only,
+        threshold=threshold,
+    )
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_search_patterns(
+    ctx: Context,
+    query: str,
+    limit: int = 5,
+    problem_type: Optional[str] = None,
+    threshold: float = 0.5,
+) -> str:
+    """Search for reusable solution patterns, ranked by similarity and success rate.
+
+    Args:
+        query: Problem description
+        limit: Max results (default 5)
+        problem_type: Filter: bug_fix, feature, refactor, config, performance
+        threshold: Minimum similarity 0-1 (default 0.5)
+    """
+    app = _get_app(ctx)
+    result = await search_patterns(
+        db=app.db,
+        embeddings=app.embeddings,
+        query=query,
+        limit=limit,
+        problem_type=problem_type,
+        threshold=threshold,
+    )
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_store_pattern(
+    ctx: Context,
+    name: str,
+    solution: str,
+    problem_type: Optional[str] = None,
+    tech_context: Optional[List[str]] = None,
+) -> str:
+    """Store a reusable solution pattern for future reference.
+
+    Args:
+        name: Pattern name
+        solution: The solution
+        problem_type: Type: bug_fix, feature, refactor, config, performance
+        tech_context: Technologies this applies to
+    """
+    app = _get_app(ctx)
+    result = await store_pattern(
+        db=app.db,
+        embeddings=app.embeddings,
+        name=name,
+        solution=solution,
+        problem_type=problem_type,
+        tech_context=tech_context,
+    )
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_store_project(
+    ctx: Context,
+    path: str,
+    name: Optional[str] = None,
+    project_type: Optional[str] = None,
+    tech_stack: Optional[List[str]] = None,
+    conventions: Optional[Dict[str, Any]] = None,
+    preferences: Optional[Dict[str, Any]] = None,
+) -> str:
+    """Store project info (tech stack, conventions, preferences).
+
+    Args:
+        path: Project path
+        name: Project name
+        project_type: Project type
+        tech_stack: Technologies used
+        conventions: Coding conventions dict
+        preferences: User preferences dict
+    """
+    app = _get_app(ctx)
+    result = await store_project(
+        db=app.db,
+        path=path,
+        name=name,
+        project_type=project_type,
+        tech_stack=tech_stack,
+        conventions=conventions,
+        preferences=preferences,
+    )
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_get_project(
+    ctx: Context,
+    project_path: str,
+) -> str:
+    """Get stored info about a project.
+
+    Args:
+        project_path: Project path to look up
+    """
+    app = _get_app(ctx)
+    result = await app.db.get_project(project_path)
+    if result is None:
+        return json.dumps({"found": False, "project_path": project_path})
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_context(
+    ctx: Context,
+    project_path: Optional[str] = None,
+    query: Optional[str] = None,
+    include_decisions: bool = True,
+    include_errors: bool = True,
+    include_patterns: bool = True,
+) -> str:
+    """Load relevant memories for the current session. Call at session start to get
+    project info, recent decisions, patterns, and relevant past errors/solutions.
+
+    Args:
+        project_path: Project path (optional, filters results)
+        query: Optional semantic query to find relevant memories
+        include_decisions: Include recent decisions (default true)
+        include_errors: Include recent errors (default true)
+        include_patterns: Include solution patterns (default true)
+    """
+    app = _get_app(ctx)
+    result: Dict[str, Any] = {}
+
+    # Project context (includes decisions, code patterns, and query-relevant memories)
+    if project_path:
+        project_ctx = await get_project_context(
+            db=app.db,
+            embeddings=app.embeddings,
+            project_path=project_path,
+            query=query,
+        )
+        result["project"] = project_ctx
+
+    # Solution patterns (when a query is provided)
+    if include_patterns and query:
+        patterns = await search_patterns(
+            db=app.db,
+            embeddings=app.embeddings,
+            query=query,
+            limit=5,
+        )
+        result["patterns"] = patterns
+
+    # Recent errors (when requested and query provided)
+    if include_errors and query:
+        errors = await semantic_search(
+            db=app.db,
+            embeddings=app.embeddings,
+            query=query,
+            limit=5,
+            memory_type="error",
+            project_path=project_path,
+        )
+        result["recent_errors"] = errors
+
+    # Stats
+    try:
+        stats = await app.db.get_stats()
+        result["stats"] = stats
+    except Exception as e:
+        result["stats_error"] = str(e)
+
+    result["success"] = True
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_stats(ctx: Context) -> str:
+    """Get memory statistics including total memories, database size, and breakdown by type."""
+    app = _get_app(ctx)
+    result = await app.db.get_stats()
+    return json.dumps(result, default=str)
+
+
+@mcp_server.tool()
+async def memory_dashboard(ctx: Context) -> str:
+    """Open the Claude Memory real-time dashboard in the browser."""
+    import webbrowser
+
+    url = config.get_dashboard_url()
+    try:
+        webbrowser.open(url)
+        return json.dumps({
+            "success": True,
+            "url": url,
+            "message": f"Dashboard opened at {url}",
+        })
+    except Exception as e:
+        return json.dumps({
+            "success": False,
+            "url": url,
+            "error": str(e),
+            "message": f"Could not auto-open browser. Visit {url} manually.",
+        })
+
+
+@mcp_server.tool()
+async def memory_sync_native(
+    ctx: Context,
+    project_path: Optional[str] = None,
+    direction: str = "both",
+) -> str:
+    """Sync between MCP DB and Claude's native MEMORY.md.
+
+    Bridges the MCP vector memory DB with Claude Code's built-in auto memory
+    (~/.claude/projects/<slug>/memory/MEMORY.md).
+
+    Args:
+        project_path: Project path to sync. If omitted, syncs current project.
+        direction: 'to_native' (MCP->MEMORY.md), 'from_native' (MEMORY.md->MCP), or 'both'
+    """
+    from services.native_memory_sync import (
+        sync_mcp_to_native,
+        sync_native_to_mcp,
+        sync_bidirectional,
+    )
+
+    app = _get_app(ctx)
+
+    if not project_path:
+        return json.dumps({
+            "success": False,
+            "error": "project_path is required for native memory sync",
+        })
+
+    try:
+        if direction == "to_native":
+            result = await sync_mcp_to_native(app.db, project_path)
+        elif direction == "from_native":
+            result = await sync_native_to_mcp(app.db, app.embeddings, project_path)
+        elif direction == "both":
+            result = await sync_bidirectional(app.db, app.embeddings, project_path)
+        else:
+            return json.dumps({
+                "success": False,
+                "error": f"Invalid direction '{direction}'. Use 'to_native', 'from_native', or 'both'.",
+            })
+
+        return json.dumps(result, default=str)
+    except Exception as e:
+        logger.error(f"memory_sync_native failed: {e}")
+        return json.dumps({"success": False, "error": str(e)})
+
+
+# ── Entry Point ─────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")

package/package.json

@@ -1,47 +1,58 @@
-{
-  "name": "claude-memory-agent",
-  "version": "2.0.1",
-  "description": "Persistent semantic memory system for Claude Code sessions with anti-hallucination grounding",
-  "keywords": [
-    "claude",
-    "claude-code",
-    "memory",
-    "ai",
-    "mcp",
-    "semantic-search",
-    "embeddings",
-    "ollama"
-  ],
-  "author": "Claude Memory Agent Contributors",
-  "license": "MIT",
-  "bin": {
-    "claude-memory-agent": "./bin/cli.js",
-    "claude-memory": "./bin/cli.js"
-  },
-  "files": [
-    "bin/",
-    "services/",
-    "skills/",
-    "hooks/",
-    "*.py",
-    "*.md",
-    "*.txt",
-    "*.html",
-    ".env.example"
-  ],
-  "scripts": {
-    "postinstall": "node bin/postinstall.js",
-    "start": "python main.py",
-    "install-agent": "python install.py --auto",
-    "test": "python -m pytest"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "os": [
-    "win32",
-    "darwin",
-    "linux"
-  ],
-  "preferGlobal": true
-}
+{
+  "name": "claude-memory-agent",
+  "version": "2.2.0",
+  "description": "Persistent semantic memory system for Claude Code sessions with anti-hallucination grounding",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "ai",
+    "mcp",
+    "semantic-search",
+    "embeddings",
+    "ollama"
+  ],
+  "author": "Claude Memory Agent Contributors",
+  "license": "MIT",
+  "bin": {
+    "claude-memory-agent": "./bin/cli.js",
+    "claude-memory": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "services/",
+    "skills/",
+    "hooks/",
+    "*.py",
+    "*.md",
+    "*.txt",
+    "*.html",
+    ".env.example",
+    "!**/__pycache__/",
+    "!**/*.pyc",
+    "!test_*.py",
+    "!verify_db.py"
+  ],
+  "scripts": {
+    "postinstall": "node bin/postinstall.js",
+    "start": "python main.py",
+    "install-agent": "python install.py --auto",
+    "test": "python -m pytest"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "preferGlobal": true,
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "boxen": "^5.1.2",
+    "chalk": "^4.1.2",
+    "gradient-string": "^2.0.2",
+    "ora": "^5.4.1"
+  }
+}

package/requirements.txt

@@ -1,8 +1,12 @@
-fastapi>=0.109.0
-uvicorn>=0.27.0
-ollama>=0.4.0
-python-dotenv>=1.0.0
-pydantic>=2.0.0
-httpx>=0.27.0
-numpy>=1.26.0
-faiss-cpu>=1.7.4
+fastapi>=0.109.0,<1.0.0
+uvicorn>=0.27.0,<1.0.0
+ollama>=0.4.0,<1.0.0  # Optional: only needed for Ollama provider
+python-dotenv>=1.0.0,<2.0.0
+pydantic>=2.0.0,<3.0.0
+httpx>=0.27.0,<1.0.0
+numpy>=1.26.0,<3.0.0
+torch>=2.0.0
+sentence-transformers>=3.0.0,<4.0.0
+faiss-cpu>=1.7.4,<2.0.0
+rich>=13.0.0,<14.0.0
+mcp>=1.0.0

package/services/__init__.py

@@ -1,50 +1,50 @@
-from .database import DatabaseService
-from .embeddings import EmbeddingService
-
-# Moltbot-inspired transparency services
-from .daily_log import (
-    append_entry as daily_log_append,
-    append_session_summary as daily_log_append_session,
-    load_recent_logs as daily_log_read,
-    get_today_highlights as daily_log_highlights,
-    list_logs as daily_log_list,
-    get_log_path
-)
-from .memory_md_sync import (
-    sync_to_memory_md,
-    read_memory_md,
-    add_fact as add_memory_md_fact,
-    get_memory_md_summary,
-    get_memory_md_path
-)
-from .compaction_flush import (
-    check_flush_needed,
-    execute_flush as pre_compaction_flush,
-    list_flushes,
-    read_flush,
-    get_flush_path
-)
-
-__all__ = [
-    "DatabaseService",
-    "EmbeddingService",
-    # Daily log
-    "daily_log_append",
-    "daily_log_append_session",
-    "daily_log_read",
-    "daily_log_highlights",
-    "daily_log_list",
-    "get_log_path",
-    # MEMORY.md
-    "sync_to_memory_md",
-    "read_memory_md",
-    "add_memory_md_fact",
-    "get_memory_md_summary",
-    "get_memory_md_path",
-    # Compaction flush
-    "check_flush_needed",
-    "pre_compaction_flush",
-    "list_flushes",
-    "read_flush",
-    "get_flush_path",
-]
+from .database import DatabaseService
+from .embeddings import EmbeddingService
+
+# Moltbot-inspired transparency services
+from .daily_log import (
+    append_entry as daily_log_append,
+    append_session_summary as daily_log_append_session,
+    load_recent_logs as daily_log_read,
+    get_today_highlights as daily_log_highlights,
+    list_logs as daily_log_list,
+    get_log_path
+)
+from .memory_md_sync import (
+    sync_to_memory_md,
+    read_memory_md,
+    add_fact as add_memory_md_fact,
+    get_memory_md_summary,
+    get_memory_md_path
+)
+from .compaction_flush import (
+    check_flush_needed,
+    execute_flush as pre_compaction_flush,
+    list_flushes,
+    read_flush,
+    get_flush_path
+)
+
+__all__ = [
+    "DatabaseService",
+    "EmbeddingService",
+    # Daily log
+    "daily_log_append",
+    "daily_log_append_session",
+    "daily_log_read",
+    "daily_log_highlights",
+    "daily_log_list",
+    "get_log_path",
+    # MEMORY.md
+    "sync_to_memory_md",
+    "read_memory_md",
+    "add_memory_md_fact",
+    "get_memory_md_summary",
+    "get_memory_md_path",
+    # Compaction flush
+    "check_flush_needed",
+    "pre_compaction_flush",
+    "list_flushes",
+    "read_flush",
+    "get_flush_path",
+]