agentcache-core 0.9.9__py3-none-any.whl

agentcache/__init__.py

@@ -0,0 +1,29 @@
+"""
+agentcache — A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite.
+"""
+
+__version__ = "0.9.9"
+
+from .app import create_app
+from .connect import run_connect
+from .core import KV, ObservationEvents, ObservationStore, SearchService
+from .db import StateKV
+from .legacy import (
+    folder_graph_build,
+    health_check,
+    remember,
+)
+
+__all__ = [
+    "__version__",
+    "create_app",
+    "StateKV",
+    "run_connect",
+    "KV",
+    "ObservationStore",
+    "ObservationEvents",
+    "SearchService",
+    "folder_graph_build",
+    "remember",
+    "health_check",
+]

agentcache/app.py

@@ -0,0 +1,312 @@
+"""
+agentmemory-python — Flask application factory.
+
+Entry point: create_app() returns a fully configured Flask app.
+Run directly:  python src/app.py
+"""
+
+import hmac
+import json
+import os
+import sys
+
+from flask import Flask, request, send_from_directory
+from flask_sock import Sock
+
+from . import legacy
+
+# Prevent double-import of app when run directly as __main__
+if __name__ == "__main__":
+    sys.modules["app"] = sys.modules["__main__"]
+
+
+def _load_env() -> None:
+    env_path = os.path.join(os.path.expanduser("~"), ".agentcache", ".env")
+    if not os.path.exists(env_path):
+        env_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".env")
+    if not os.path.exists(env_path):
+        return
+    try:
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                k, v = line.split("=", 1)
+                os.environ[k.strip()] = v.strip().strip('"').strip("'")
+        print(f"[config] Loaded environment from {env_path}")
+    except Exception as e:
+        print(f"[config] Error reading env file: {e}")
+
+
+_load_env()
+
+# Module-level singletons — set once by init_services(), read by blueprints and workers.
+kv = None
+embedding_provider = None
+persistence = None  # kept for backward compat with workers; use search_service instead
+search_service = None  # SearchService instance
+observation_store = None  # ObservationStore instance
+
+
+def init_services() -> tuple:
+    """Initialise database, SearchService, ObservationStore, and legacy persistence shim."""
+    global kv, embedding_provider, persistence, search_service, observation_store
+    if kv is not None:
+        return kv, embedding_provider, persistence
+
+    from . import search as search_mod
+    from .core.observation_store import ObservationEvents, ObservationStore
+    from .core.search_service import SearchService
+    from .db import StateKV
+    from .search import SearchIndex, VectorIndex
+
+    # 1. DB
+    kv = StateKV()
+
+    # 2. Embedding provider — auto-select by priority:
+    #    GEMINI_API_KEY → OPENAI_API_KEY → AGENTCACHE_LOCAL_EMBEDDING_MODEL → BM25-only
+    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+    openai_key = os.getenv("OPENAI_API_KEY")
+    local_model = os.getenv("AGENTCACHE_LOCAL_EMBEDDING_MODEL") or os.getenv(
+        "AGENTMEMORY_LOCAL_EMBEDDING_MODEL"
+    )
+
+    if api_key:
+        try:
+            embedding_provider = search_mod.GeminiEmbeddingProvider(api_key)
+            print(
+                f"[search] Embedding provider active: gemini ({embedding_provider.dimensions} dims)"
+            )
+        except Exception as e:
+            print(f"[search] Error initialising Gemini embedding provider: {e}")
+    elif openai_key:
+        try:
+            embedding_provider = search_mod.OpenAIEmbeddingProvider(openai_key)
+            print(
+                f"[search] Embedding provider active: openai ({embedding_provider.dimensions} dims)"
+            )
+        except Exception as e:
+            print(f"[search] Error initialising OpenAI embedding provider: {e}")
+    elif local_model:
+        try:
+            embedding_provider = search_mod.SentenceTransformerProvider(local_model)
+            print(
+                f"[search] Embedding provider active: sentence-transformers/{local_model} ({embedding_provider.dimensions} dims)"
+            )
+        except ImportError as e:
+            print(f"[search] sentence-transformers not installed: {e}")
+        except Exception as e:
+            print(f"[search] Error initialising SentenceTransformer provider: {e}")
+    else:
+        print("[search] No embedding API key found — running in BM25-only mode.")
+
+    # 3. Construct SearchService and ObservationStore with injected dependencies.
+    bm25 = SearchIndex()
+    vector = VectorIndex() if embedding_provider is not None else None
+    search_service = SearchService(bm25, vector, embedding_provider, kv)
+    observation_store = ObservationStore(
+        kv, search_service=search_service, events=ObservationEvents()
+    )
+
+    # Load persisted indexes.
+    loaded = search_service.load_persisted()
+    print(
+        f"[persistence] Load results: BM25={loaded['bm25']}, Vector={loaded['vector']}"
+    )
+
+    # Keep persistence reference for workers backward compat.
+    persistence = search_service._persistence
+
+    # Backfill coordinate lookup index if missing/incomplete.
+    try:
+        if observation_store is not None:
+            observation_store.backfill_lookup()
+    except Exception as e:
+        print(f"[db] Warning backfilling obs_lookup: {e}")
+
+    return kv, embedding_provider, persistence
+
+
+def create_app() -> Flask:
+    """Create and return a fully configured Flask application."""
+    # Check security credentials
+    if not os.getenv("AGENTCACHE_SECRET") and not os.getenv("AGENTMEMORY_SECRET"):
+        print(
+            "[security] WARNING: AGENTCACHE_SECRET/AGENTMEMORY_SECRET is not set! All API endpoints are publicly accessible without authentication."
+        )
+
+    init_services()
+
+    from .viewer_helpers import make_viewer_response
+
+    # 4. Flask app + blueprints
+    flask_app = Flask(__name__)
+    flask_app.extensions["kv"] = kv
+    flask_app.extensions["observation_store"] = observation_store
+    flask_app.extensions["search_service"] = search_service
+
+    from werkzeug.middleware.proxy_fix import ProxyFix
+
+    flask_app.wsgi_app = ProxyFix(
+        flask_app.wsgi_app, x_proto=1, x_host=1, x_port=1, x_prefix=1
+    )
+    from .routes import register_blueprints
+
+    register_blueprints(
+        flask_app, observation_store=observation_store, search_service=search_service
+    )
+
+    # 5. WebSocket broadcaster
+    sock = Sock(flask_app)
+    _ws_clients: set = set()
+
+    @sock.route("/stream/mem-live/viewer")
+    def stream_viewer(ws):
+        secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
+        if secret:
+            token = request.args.get("token") or request.args.get("secret")
+            if not token or not hmac.compare_digest(
+                token.encode("utf-8"), secret.encode("utf-8")
+            ):
+                ws.close(1008)
+                return
+        _ws_clients.add(ws)
+        try:
+            while ws.receive() is not None:
+                pass
+        except Exception:
+            pass
+        finally:
+            _ws_clients.discard(ws)
+
+    def _broadcast(payload: dict) -> None:
+        msg = json.dumps(payload)
+        for ws in list(_ws_clients):
+            try:
+                ws.send(msg)
+            except Exception:
+                _ws_clients.discard(ws)
+
+    legacy.set_stream_broadcaster(_broadcast)
+
+    if observation_store and observation_store.events:
+        observation_store.events.on_added.append(_broadcast)
+
+    # 6. Viewer static routes
+    from importlib.resources import files
+
+    _viewer_resources = files("agentcache").joinpath("viewer")
+    _base_dir = str(_viewer_resources.parent)
+
+    @flask_app.route("/")
+    @flask_app.route("/viewer")
+    @flask_app.route("/agentcache/viewer")
+    @flask_app.route("/agentmemory/viewer")
+    def serve_viewer():
+        try:
+            return make_viewer_response(_base_dir)
+        except Exception as e:
+            return f"Viewer not found: {e}", 404
+
+    @flask_app.route("/favicon.svg")
+    def serve_favicon():
+        return send_from_directory(str(_viewer_resources), "favicon.svg")
+
+    # 7. CORS after_request — D2.1: configurable via AGENTCACHE_CORS_ORIGINS env var
+    # Default allows localhost, 127.0.0.1, HuggingFace Spaces, vscode-webview://, chrome-extension://
+    # Wildcard entries like "*.hf.space" match any subdomain via suffix check.
+    _default_cors = (
+        "http://localhost,http://127.0.0.1,"
+        "https://huggingface.co,https://*.hf.space,"
+        "vscode-webview://*,chrome-extension://*"
+    )
+    _cors_origins_raw = (
+        os.getenv("AGENTCACHE_CORS_ORIGINS")
+        or os.getenv("AGENTMEMORY_CORS_ORIGINS")
+        or _default_cors
+    )
+
+    def _parse_cors_origins(raw: str):
+        """Return (exact_set, suffix_list) for efficient origin matching."""
+        exact, suffixes = set(), []
+        for entry in raw.split(","):
+            entry = entry.strip()
+            if not entry:
+                continue
+            if entry.startswith("*."):
+                # *.hf.space → match anything ending with .hf.space
+                suffixes.append(entry[1:].lower())  # keep the leading dot: ".hf.space"
+            elif "*" in entry:
+                # generic prefix wildcard: strip trailing * and treat as prefix
+                suffixes.append(("prefix:", entry.rstrip("*").lower()))
+            else:
+                exact.add(entry.lower())
+        return exact, suffixes
+
+    _cors_exact, _cors_suffixes = _parse_cors_origins(_cors_origins_raw)
+
+    def _origin_allowed(origin: str) -> bool:
+        lo = origin.lower()
+        if lo in _cors_exact:
+            return True
+        for s in _cors_suffixes:
+            if isinstance(s, tuple) and s[0] == "prefix:":
+                if lo.startswith(s[1]):
+                    return True
+            elif lo.endswith(s):
+                return True
+        return False
+
+    @flask_app.after_request
+    def _cors(response):
+        origin = request.headers.get("Origin")
+        if origin and _origin_allowed(origin):
+            response.headers["Access-Control-Allow-Origin"] = origin
+            response.headers["Access-Control-Allow-Credentials"] = "true"
+        response.headers.add(
+            "Access-Control-Allow-Headers", "Content-Type, Authorization"
+        )
+        response.headers.add(
+            "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS"
+        )
+        return response
+
+    # Handle CORS preflight OPTIONS requests globally
+    from flask import Response as _FlaskResponse
+
+    @flask_app.before_request
+    def _handle_options():
+        if request.method == "OPTIONS":
+            origin = request.headers.get("Origin", "")
+            if origin and _origin_allowed(origin):
+                resp = _FlaskResponse("", status=204)
+                resp.headers["Access-Control-Allow-Origin"] = origin
+                resp.headers["Access-Control-Allow-Credentials"] = "true"
+                resp.headers["Access-Control-Allow-Headers"] = (
+                    "Content-Type, Authorization"
+                )
+                resp.headers["Access-Control-Allow-Methods"] = (
+                    "GET, POST, PUT, DELETE, OPTIONS"
+                )
+                resp.headers["Access-Control-Max-Age"] = "86400"
+                return resp
+
+    # 8. Background workers
+    if os.getenv("AGENTCACHE_DISABLE_WORKERS") != "true":
+        from .workers import start_background_workers
+
+        start_background_workers(kv)
+
+    return flask_app
+
+
+def main() -> None:
+    flask_app = create_app()
+    port = int(os.getenv("III_REST_PORT", os.getenv("PORT", "3111")))
+    print(f"[main] Starting Flask daemon on port {port}...")
+    flask_app.run(host="0.0.0.0", port=port, debug=False)  # nosec B104
+
+
+if __name__ == "__main__":
+    main()

agentcache/cli.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+"""
+agentcache CLI entrypoint.
+
+Commands:
+  agentcache serve [--port PORT] [--host HOST]
+  agentcache migrate [--dry-run]
+  agentcache export [--output FILE]
+"""
+
+import argparse
+import json
+import os
+
+
+def cmd_serve(args) -> None:
+    """Start the Flask server."""
+    os.environ.setdefault("III_REST_PORT", str(args.port))
+    if getattr(args, "no_workers", False):
+        os.environ["AGENTCACHE_DISABLE_WORKERS"] = "true"
+    from .app import create_app
+
+    flask_app = create_app()
+    print(f"[cli] Starting agentcache on {args.host}:{args.port}")
+    flask_app.run(host=args.host, port=args.port, debug=False)
+
+
+def cmd_migrate(args) -> None:
+    """Run session → folder migration."""
+    from .db import StateKV
+    from .legacy import migrate_sessions_to_folders
+
+    kv = StateKV()
+    result = migrate_sessions_to_folders(kv, dry_run=args.dry_run)
+    print(json.dumps(result, indent=2))
+    if args.dry_run:
+        print(
+            f"\n[cli] Dry run — no changes made. "
+            f"{result['migrated_sessions']} sessions, "
+            f"{result['migrated_observations']} observations would be migrated."
+        )
+    else:
+        print(
+            f"\n[cli] Migration complete: "
+            f"{result['migrated_sessions']} sessions, "
+            f"{result['migrated_observations']} observations migrated."
+        )
+    if result.get("errors"):
+        print(f"[cli] {len(result['errors'])} errors:")
+        for e in result["errors"]:
+            print(f"  - {e}")
+
+
+def cmd_export(args) -> None:
+    """Export all data as JSON."""
+    from .db import StateKV
+    from .legacy import export_data
+
+    kv = StateKV()
+    data = export_data(kv, {})
+    output = json.dumps(data, indent=2, ensure_ascii=False)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output)
+        print(f"[cli] Exported to {args.output}")
+        total_obs = sum(
+            len(folder.get("observations", [])) for folder in data.get("folders", [])
+        )
+        print(
+            f"[cli] {len(data.get('folders', []))} folders, {total_obs} observations, "
+            f"{len(data.get('memories', []))} memories"
+        )
+    else:
+        print(output)
+
+
+def cmd_connect(args) -> None:
+    """Connect/wire MCP and hooks to client agents."""
+    from .connect import run_connect
+
+    run_connect(args)
+
+
+def cmd_worker(args) -> None:
+    """Run background worker tasks in a dedicated process."""
+    import time
+
+    tasks = [t.strip() for t in args.tasks.split(",")]
+    print(f"[worker] Starting worker process for tasks: {tasks}")
+
+    from .app import init_services
+
+    kv, _, _ = init_services()
+
+    from .workers import _shutting_down, start_background_workers
+
+    start_background_workers(kv, tasks=tasks)
+
+    try:
+        while not _shutting_down.is_set():
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("[worker] KeyboardInterrupt received. Initiating shutdown...")
+        import signal
+
+        from .workers import _shutdown_handler
+
+        _shutdown_handler(signal.SIGINT, None)
+
+
+def cmd_context(args) -> None:
+    """Generate or watch .agentcache_context.md in the current folder."""
+    import time
+
+    from .app import init_services
+    from .core import KV
+    from .core.observation_store import normalize_folder_path
+
+    # 1. Resolve folder and agent
+    cwd = os.getcwd()
+    try:
+        folder_path = normalize_folder_path(cwd)
+    except Exception as e:
+        print(f"[cli] Failed to normalize current path: {e}")
+        return
+
+    agent_id = args.agent or os.getenv("AGENT_ID") or "agent"
+    output_file = args.output or ".agentcache_context.md"
+
+    print(f"[context] Target: {folder_path} (agent: {agent_id}) -> {output_file}")
+
+    # 2. Init DB services
+    kv, _, _ = init_services()
+
+    def generate_context() -> str:
+        # Fetch metadata
+        meta = kv.get(KV.folder_meta(folder_path, agent_id), "meta") or {}
+        obs_count = meta.get("obsCount", 0)
+        last_updated = meta.get("lastUpdated", "Never")
+
+        # Fetch recent observations (sorted desc by timestamp)
+        obs_list = kv.list(KV.folder_obs(folder_path, agent_id))
+        obs_list = sorted(obs_list, key=lambda x: x.get("timestamp", ""), reverse=True)
+        recent_obs = obs_list[:5]
+
+        # Fetch memories relevant to this agent or project (case-insensitive match)
+        folder_name = os.path.basename(cwd) or "Workspace"
+        project_name = folder_name.strip().lower()
+
+        memories = kv.list(KV.memories)
+        relevant_memories = []
+        for m in memories:
+            if m.get("isLatest") is False:
+                continue
+
+            match_agent = m.get("agentId") == agent_id
+            m_proj = m.get("project")
+            match_project = m_proj and m_proj.strip().lower() == project_name
+
+            if match_agent or match_project:
+                relevant_memories.append(m)
+
+        relevant_memories = sorted(
+            relevant_memories, key=lambda x: x.get("updatedAt", ""), reverse=True
+        )
+        recent_memories = relevant_memories[:5]
+
+        lines = [
+            "<!-- Generated by agentcache. DO NOT EDIT. -->",
+            f"# Agent Cache Context - {folder_name}",
+            "",
+            "## Project Metadata",
+            f"- **Path:** `{folder_path}`",
+            f"- **Agent ID:** `{agent_id}`",
+            f"- **Total Observations:** {obs_count}",
+            f"- **Last Updated:** {last_updated}",
+            "",
+            "## Pinned Memories & Lessons",
+        ]
+
+        if not recent_memories:
+            lines.append("No active long-term memories registered for this agent.")
+        else:
+            for mem in recent_memories:
+                m_type = mem.get("type", "fact").upper()
+                lines.append(f"### [{m_type}] {mem.get('title', 'Untitled')}")
+                lines.append(f"{mem.get('content', '')}")
+                lines.append("")
+
+        lines.extend(["", "## Recent Activity Timeline (Last 5 Observations)", ""])
+
+        if not recent_obs:
+            lines.append("No observations logged yet in this workspace.")
+        else:
+            for obs in recent_obs:
+                ts = obs.get("timestamp", "")
+                o_type = obs.get("type", "observation")
+                text = obs.get("text", "")
+                lines.append(f"- **[{ts}] ({o_type}):** {text.strip()}")
+
+        lines.append("")
+        return "\n".join(lines)
+
+    def write_context():
+        content = generate_context()
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"[context] Updated {output_file}")
+
+    # Initial write
+    write_context()
+
+    print(
+        "[context] Tip: Add the following instruction to your IDE's system prompt or .cursorrules to automatically load this cache context:"
+    )
+    print(
+        "--------------------------------------------------------------------------------"
+    )
+    print(
+        "Always load and inspect the local `.agentcache_context.md` file at the start of"
+    )
+    print(
+        "your session to retrieve the latest project state, lessons, and pinned memories."
+    )
+    print(
+        "--------------------------------------------------------------------------------"
+    )
+
+    if args.watch:
+        print("[context] Watching for database changes. Press Ctrl+C to stop...")
+        last_meta_state = None
+        try:
+            while True:
+                # Check meta state change
+                meta = kv.get(KV.folder_meta(folder_path, agent_id), "meta") or {}
+                meta_state = (meta.get("obsCount", 0), meta.get("lastUpdated", ""))
+                if meta_state != last_meta_state:
+                    if last_meta_state is not None:
+                        write_context()
+                    last_meta_state = meta_state
+                time.sleep(2)
+        except KeyboardInterrupt:
+            print("[context] Watcher stopped.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentcache",
+        description="agentcache — AI agent cache server",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # serve
+    serve_parser = subparsers.add_parser("serve", help="Start the cache server")
+    serve_parser.add_argument(
+        "--port", type=int, default=int(os.getenv("III_REST_PORT", "3111"))
+    )
+    serve_parser.add_argument("--host", default="0.0.0.0")  # nosec B104
+    serve_parser.add_argument(
+        "--no-workers", action="store_true", help="Disable background worker threads"
+    )
+
+    # worker
+    worker_parser = subparsers.add_parser(
+        "worker", help="Run background worker processes"
+    )
+    worker_parser.add_argument(
+        "--tasks",
+        default="index,forget",
+        help="Comma-separated tasks to run (index, forget)",
+    )
+
+    # migrate
+    migrate_parser = subparsers.add_parser(
+        "migrate", help="Migrate legacy session data to folder-based storage"
+    )
+    migrate_parser.add_argument(
+        "--dry-run", action="store_true", help="Preview without writing"
+    )
+
+    # export
+    export_parser = subparsers.add_parser("export", help="Export all data as JSON")
+    export_parser.add_argument(
+        "--output", "-o", help="Output file path (default: stdout)"
+    )
+
+    # context
+    context_parser = subparsers.add_parser(
+        "context", help="Generate or watch .agentcache_context.md local file"
+    )
+    context_parser.add_argument(
+        "--agent", help="Specify agent ID (defaults to AGENT_ID or 'agent')"
+    )
+    context_parser.add_argument(
+        "--output", "-o", help="Output file path (default: .agentcache_context.md)"
+    )
+    context_parser.add_argument(
+        "--watch", action="store_true", help="Watch for updates in real-time"
+    )
+
+    # connect
+    connect_parser = subparsers.add_parser(
+        "connect", help="Connect/wire MCP and hooks to client agents"
+    )
+    connect_parser.add_argument(
+        "agent",
+        nargs="?",
+        help="Specify target agent (antigravity, claude-code, kiro, etc.)",
+    )
+    connect_parser.add_argument(
+        "--with-hooks",
+        action="store_true",
+        help="Install global workspace hook execution blocks (Claude/Codex).",
+    )
+    connect_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Log proposed configuration modifications without writing.",
+    )
+    connect_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing configuration settings.",
+    )
+    connect_parser.add_argument(
+        "--all", action="store_true", help="Attempt connection to all detected agents."
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "serve":
+        cmd_serve(args)
+    elif args.command == "worker":
+        cmd_worker(args)
+    elif args.command == "migrate":
+        cmd_migrate(args)
+    elif args.command == "export":
+        cmd_export(args)
+    elif args.command == "context":
+        cmd_context(args)
+    elif args.command == "connect":
+        cmd_connect(args)
+
+
+if __name__ == "__main__":
+    main()