alma-memory 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

alma/mcp/__init__.py

@@ -1,45 +1,123 @@
-"""
-ALMA MCP Server Module.
-
-Exposes ALMA functionality to any Claude Code instance via the
-Model Context Protocol (MCP).
-
-Usage:
-    # stdio mode (for Claude Code integration)
-    python -m alma.mcp --config .alma/config.yaml
-
-    # HTTP mode (for remote access)
-    python -m alma.mcp --http --port 8765
-
-Integration with Claude Code (.mcp.json):
-    {
-        "mcpServers": {
-            "alma-memory": {
-                "command": "python",
-                "args": ["-m", "alma.mcp", "--config", ".alma/config.yaml"]
-            }
-        }
-    }
-"""
-
-from alma.mcp.server import ALMAMCPServer
-from alma.mcp.tools import (
-    alma_add_knowledge,
-    alma_add_preference,
-    alma_forget,
-    alma_health,
-    alma_learn,
-    alma_retrieve,
-    alma_stats,
-)
-
-__all__ = [
-    "ALMAMCPServer",
-    "alma_retrieve",
-    "alma_learn",
-    "alma_add_preference",
-    "alma_add_knowledge",
-    "alma_forget",
-    "alma_stats",
-    "alma_health",
-]
+"""
+ALMA MCP Server Module.
+
+Exposes ALMA functionality to any Claude Code instance via the
+Model Context Protocol (MCP).
+
+Usage:
+    # stdio mode (for Claude Code integration)
+    python -m alma.mcp --config .alma/config.yaml
+
+    # HTTP mode (for remote access)
+    python -m alma.mcp --http --port 8765
+
+Integration with Claude Code (.mcp.json):
+    {
+        "mcpServers": {
+            "alma-memory": {
+                "command": "python",
+                "args": ["-m", "alma.mcp", "--config", ".alma/config.yaml"]
+            }
+        }
+    }
+
+Async API:
+    Both sync and async variants of tools are available:
+    - Sync: alma_retrieve, alma_learn, etc.
+    - Async: async_alma_retrieve, async_alma_learn, etc.
+
+Workflow Tools (v0.6.0):
+    Tools for AGtestari workflow integration:
+    - alma_checkpoint: Create crash recovery checkpoints
+    - alma_resume: Get checkpoint to resume from
+    - alma_merge_states: Merge parallel branch states
+    - alma_workflow_learn: Record workflow outcomes
+    - alma_link_artifact: Link artifacts to memories
+    - alma_get_artifacts: Get artifacts for a memory
+    - alma_cleanup_checkpoints: Clean up old checkpoints
+    - alma_retrieve_scoped: Scoped memory retrieval
+"""
+
+from alma.mcp.server import ALMAMCPServer
+from alma.mcp.tools import (
+    # Sync tools
+    alma_add_knowledge,
+    alma_add_preference,
+    # Workflow tools (v0.6.0)
+    alma_checkpoint,
+    alma_cleanup_checkpoints,
+    alma_consolidate,
+    alma_forget,
+    alma_get_artifacts,
+    alma_health,
+    alma_learn,
+    alma_link_artifact,
+    alma_merge_states,
+    alma_resume,
+    alma_retrieve,
+    # Mode-aware tools (v0.7.0)
+    alma_retrieve_for_mode,
+    alma_retrieve_scoped,
+    alma_retrieve_smart,
+    alma_stats,
+    alma_workflow_learn,
+    # Async tools
+    async_alma_add_knowledge,
+    async_alma_add_preference,
+    # Async workflow tools
+    async_alma_checkpoint,
+    async_alma_forget,
+    async_alma_health,
+    async_alma_learn,
+    async_alma_link_artifact,
+    async_alma_resume,
+    async_alma_retrieve,
+    # Async mode-aware tools (v0.7.0)
+    async_alma_retrieve_for_mode,
+    async_alma_retrieve_scoped,
+    async_alma_retrieve_smart,
+    async_alma_stats,
+    async_alma_workflow_learn,
+)
+
+__all__ = [
+    "ALMAMCPServer",
+    # Sync tools
+    "alma_retrieve",
+    "alma_learn",
+    "alma_add_preference",
+    "alma_add_knowledge",
+    "alma_forget",
+    "alma_stats",
+    "alma_health",
+    "alma_consolidate",
+    # Workflow tools (v0.6.0)
+    "alma_checkpoint",
+    "alma_resume",
+    "alma_merge_states",
+    "alma_workflow_learn",
+    "alma_link_artifact",
+    "alma_get_artifacts",
+    "alma_cleanup_checkpoints",
+    "alma_retrieve_scoped",
+    # Mode-aware tools (v0.7.0)
+    "alma_retrieve_for_mode",
+    "alma_retrieve_smart",
+    # Async tools
+    "async_alma_retrieve",
+    "async_alma_learn",
+    "async_alma_add_preference",
+    "async_alma_add_knowledge",
+    "async_alma_forget",
+    "async_alma_stats",
+    "async_alma_health",
+    # Async workflow tools
+    "async_alma_checkpoint",
+    "async_alma_resume",
+    "async_alma_workflow_learn",
+    "async_alma_link_artifact",
+    "async_alma_retrieve_scoped",
+    # Async mode-aware tools (v0.7.0)
+    "async_alma_retrieve_for_mode",
+    "async_alma_retrieve_smart",
+]

alma/mcp/__main__.py

@@ -1,156 +1,156 @@
-"""
-ALMA MCP Server CLI Entry Point.
-
-Usage:
-    # stdio mode (for Claude Code)
-    python -m alma.mcp --config .alma/config.yaml
-
-    # HTTP mode (for remote access)
-    python -m alma.mcp --http --port 8765
-
-    # With verbose logging
-    python -m alma.mcp --config .alma/config.yaml --verbose
-"""
-
-import argparse
-import asyncio
-import logging
-import sys
-from pathlib import Path
-
-from alma import ALMA
-from alma.mcp.server import ALMAMCPServer
-
-
-def setup_logging(verbose: bool = False):
-    """Configure logging."""
-    level = logging.DEBUG if verbose else logging.INFO
-    logging.basicConfig(
-        level=level,
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-        stream=sys.stderr,  # Log to stderr to avoid interfering with stdio
-    )
-
-
-def main():
-    """Main entry point."""
-    parser = argparse.ArgumentParser(
-        description="ALMA MCP Server - Memory for AI Agents",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-    # Start in stdio mode for Claude Code
-    python -m alma.mcp --config .alma/config.yaml
-
-    # Start in HTTP mode on port 8765
-    python -m alma.mcp --http --port 8765
-
-    # Use with verbose logging
-    python -m alma.mcp --config .alma/config.yaml --verbose
-        """,
-    )
-
-    parser.add_argument(
-        "--config",
-        type=str,
-        default=".alma/config.yaml",
-        help="Path to ALMA config file (default: .alma/config.yaml)",
-    )
-
-    parser.add_argument(
-        "--http",
-        action="store_true",
-        help="Run in HTTP mode instead of stdio",
-    )
-
-    parser.add_argument(
-        "--host",
-        type=str,
-        default="0.0.0.0",
-        help="HTTP server host (default: 0.0.0.0)",
-    )
-
-    parser.add_argument(
-        "--port",
-        type=int,
-        default=8765,
-        help="HTTP server port (default: 8765)",
-    )
-
-    parser.add_argument(
-        "--verbose",
-        "-v",
-        action="store_true",
-        help="Enable verbose logging",
-    )
-
-    args = parser.parse_args()
-
-    # Setup logging
-    setup_logging(args.verbose)
-    logger = logging.getLogger(__name__)
-
-    # Load ALMA from config
-    config_path = Path(args.config)
-    if not config_path.exists():
-        logger.error(f"Config file not found: {config_path}")
-        logger.info("Creating default config...")
-
-        # Create minimal default config
-        config_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(config_path, "w") as f:
-            f.write("""# ALMA Configuration
-alma:
-  project_id: "default"
-  storage: "file"
-  storage_dir: ".alma"
-  embedding_provider: "local"
-
-  agents:
-    helena:
-      can_learn:
-        - testing_strategies
-        - selector_patterns
-        - form_testing
-        - accessibility_testing
-      cannot_learn:
-        - backend_logic
-        - database_queries
-      min_occurrences_for_heuristic: 3
-
-    victor:
-      can_learn:
-        - api_design_patterns
-        - authentication_patterns
-        - error_handling
-        - database_query_patterns
-      cannot_learn:
-        - frontend_styling
-        - ui_testing
-      min_occurrences_for_heuristic: 3
-""")
-        logger.info(f"Created default config at {config_path}")
-
-    try:
-        alma = ALMA.from_config(str(config_path))
-        logger.info(f"Loaded ALMA from {config_path}")
-        logger.info(f"Project: {alma.project_id}")
-        logger.info(f"Agents: {list(alma.scopes.keys())}")
-
-    except Exception as e:
-        logger.exception(f"Failed to load ALMA: {e}")
-        sys.exit(1)
-
-    # Create and run server
-    server = ALMAMCPServer(alma=alma)
-
-    if args.http:
-        logger.info(f"Starting HTTP server on {args.host}:{args.port}")
-        asyncio.run(server.run_http(host=args.host, port=args.port))
-    else:
-        logger.info("Starting stdio server for Claude Code integration")
-        asyncio.run(server.run_stdio())
-
-
-if __name__ == "__main__":
-    main()
+"""
+ALMA MCP Server CLI Entry Point.
+
+Usage:
+    # stdio mode (for Claude Code)
+    python -m alma.mcp --config .alma/config.yaml
+
+    # HTTP mode (for remote access)
+    python -m alma.mcp --http --port 8765
+
+    # With verbose logging
+    python -m alma.mcp --config .alma/config.yaml --verbose
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from alma import ALMA
+from alma.mcp.server import ALMAMCPServer
+
+
+def setup_logging(verbose: bool = False):
+    """Configure logging."""
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,  # Log to stderr to avoid interfering with stdio
+    )
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="ALMA MCP Server - Memory for AI Agents",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Start in stdio mode for Claude Code
+    python -m alma.mcp --config .alma/config.yaml
+
+    # Start in HTTP mode on port 8765
+    python -m alma.mcp --http --port 8765
+
+    # Use with verbose logging
+    python -m alma.mcp --config .alma/config.yaml --verbose
+        """,
+    )
+
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=".alma/config.yaml",
+        help="Path to ALMA config file (default: .alma/config.yaml)",
+    )
+
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="Run in HTTP mode instead of stdio",
+    )
+
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="HTTP server host (default: 0.0.0.0)",
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="HTTP server port (default: 8765)",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(args.verbose)
+    logger = logging.getLogger(__name__)
+
+    # Load ALMA from config
+    config_path = Path(args.config)
+    if not config_path.exists():
+        logger.error(f"Config file not found: {config_path}")
+        logger.info("Creating default config...")
+
+        # Create minimal default config
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(config_path, "w") as f:
+            f.write("""# ALMA Configuration
+alma:
+  project_id: "default"
+  storage: "file"
+  storage_dir: ".alma"
+  embedding_provider: "local"
+
+  agents:
+    helena:
+      can_learn:
+        - testing_strategies
+        - selector_patterns
+        - form_testing
+        - accessibility_testing
+      cannot_learn:
+        - backend_logic
+        - database_queries
+      min_occurrences_for_heuristic: 3
+
+    victor:
+      can_learn:
+        - api_design_patterns
+        - authentication_patterns
+        - error_handling
+        - database_query_patterns
+      cannot_learn:
+        - frontend_styling
+        - ui_testing
+      min_occurrences_for_heuristic: 3
+""")
+        logger.info(f"Created default config at {config_path}")
+
+    try:
+        alma = ALMA.from_config(str(config_path))
+        logger.info(f"Loaded ALMA from {config_path}")
+        logger.info(f"Project: {alma.project_id}")
+        logger.info(f"Agents: {list(alma.scopes.keys())}")
+
+    except Exception as e:
+        logger.exception(f"Failed to load ALMA: {e}")
+        sys.exit(1)
+
+    # Create and run server
+    server = ALMAMCPServer(alma=alma)
+
+    if args.http:
+        logger.info(f"Starting HTTP server on {args.host}:{args.port}")
+        asyncio.run(server.run_http(host=args.host, port=args.port))
+    else:
+        logger.info("Starting stdio server for Claude Code integration")
+        asyncio.run(server.run_stdio())
+
+
+if __name__ == "__main__":
+    main()