agentcache-core 0.9.9__py3-none-any.whl

agentcache/viewer_helpers.py

@@ -0,0 +1,61 @@
+"""
+Viewer HTML rendering helpers.
+
+Separated from app.py so the factory stays under 150 lines.
+"""
+
+import base64
+import os
+import secrets
+
+from flask import make_response
+
+
+def make_viewer_response(base_dir: str):
+    """
+    Read src/viewer/index.html, inject nonce + version + token, set CSP headers.
+
+    Returns a Flask Response object ready to send to the client.
+    Raises an exception if the template file is missing.
+    """
+    template_path = os.path.join(base_dir, "viewer", "index.html")
+    with open(template_path, "r", encoding="utf-8") as f:
+        template = f.read()
+
+    nonce = (
+        base64.urlsafe_b64encode(secrets.token_bytes(16)).decode("utf-8").rstrip("=")
+    )
+
+    # D2.2: Never embed the raw AGENTCACHE_SECRET in page source.
+    # Replace the placeholder with an empty string — the viewer authenticates
+    # via the Authorization header set programmatically after load.
+    html = (
+        template.replace("__AGENTCACHE_VIEWER_NONCE__", nonce)
+        .replace("__AGENTCACHE_VERSION__", "0.9.9")
+        .replace("__AGENTCACHE_AUTO_TOKEN__", "")
+    )
+
+    csp = "; ".join(
+        [
+            "default-src 'none'",
+            "base-uri 'none'",
+            "frame-ancestors 'self' https://huggingface.co https://*.hf.space",
+            "object-src 'none'",
+            "form-action 'none'",
+            f"script-src 'nonce-{nonce}'",
+            "script-src-attr 'none'",
+            "style-src 'unsafe-inline'",
+            (
+                "connect-src 'self' https: http://localhost:* http://127.0.0.1:* "
+                "wss: ws://localhost:* ws://127.0.0.1:* wss://localhost:* wss://127.0.0.1:*"
+            ),
+            "img-src 'self' data:",
+            "font-src 'self'",
+        ]
+    )
+
+    res = make_response(html)
+    res.headers["Content-Type"] = "text/html; charset=utf-8"
+    res.headers["Content-Security-Policy"] = csp
+    res.headers["Cache-Control"] = "no-cache"
+    return res

agentcache/workers.py

@@ -0,0 +1,192 @@
+"""
+Background worker threads for agentcache-python.
+
+Start all workers via start_background_workers(kv).
+Each worker runs as a daemon thread so it exits automatically when the process dies.
+
+C5.1: SIGTERM and SIGINT handlers are registered here to flush the index
+persistence debounce queue and run a WAL checkpoint before exit.
+"""
+
+import os
+import signal
+import sys
+import threading
+import time
+
+from . import legacy
+
+# Module-level shutdown flag — set by signal handlers
+_shutting_down = threading.Event()
+
+_persistence_ref = None
+_search_svc_ref = None
+_obs_store_ref = None
+_kv_ref = None
+
+
+def _shutdown_handler(signum, frame) -> None:  # noqa: ARG001
+    """Handle SIGTERM/SIGINT gracefully (C5.1).
+
+    Steps:
+    1. Set the global _shutting_down flag to stop background loops.
+    2. Flush the debounce timer and save the index synchronously via SearchService.flush_persist().
+    3. Run a WAL checkpoint via StateKV.teardown().
+    4. Exit cleanly with code 0.
+    """
+    sig_name = signal.Signals(signum).name
+    print(f"\n[workers] Received {sig_name} — initiating graceful shutdown...")
+
+    _shutting_down.set()
+
+    global _search_svc_ref, _persistence_ref
+    if _search_svc_ref is not None:
+        try:
+            print("[workers] Flushing SearchService persistence...")
+            _search_svc_ref.flush_persist()
+            print("[workers] SearchService persistence flushed.")
+        except Exception as e:
+            print(f"[workers] Error flushing SearchService: {e}")
+    elif _persistence_ref is not None:
+        try:
+            print("[workers] Flushing index persistence...")
+            _persistence_ref.flush()
+            print("[workers] Index persistence flushed.")
+        except Exception as e:
+            print(f"[workers] Error flushing persistence: {e}")
+
+    # WAL checkpoint — flush WAL to the main DB file
+    global _kv_ref
+    if _kv_ref is not None:
+        try:
+            print("[workers] Running WAL checkpoint...")
+            _kv_ref.teardown()
+            print("[workers] WAL checkpoint complete.")
+        except Exception as e:
+            print(f"[workers] Error during WAL checkpoint: {e}")
+
+    print("[workers] Shutdown complete.")
+    sys.exit(0)
+
+
+def _register_signal_handlers() -> None:
+    """Register SIGTERM and SIGINT handlers (C5.1).
+
+    Skipped if the calling thread is not the main thread, because Python
+    only allows signal handlers to be registered from the main thread.
+    """
+    if threading.current_thread() is not threading.main_thread():
+        return
+    try:
+        signal.signal(signal.SIGTERM, _shutdown_handler)
+        signal.signal(signal.SIGINT, _shutdown_handler)
+        print("[workers] Signal handlers registered (SIGTERM, SIGINT).")
+    except (OSError, ValueError) as e:
+        # Some environments (e.g. Windows without signal support) may raise here
+        print(f"[workers] Could not register signal handlers: {e}")
+
+
+def _auto_forget_loop(kv) -> None:
+    """Periodically sweep and evict stale observations (configurable via AUTO_FORGET_ENABLED)."""
+    time.sleep(10)
+    while not _shutting_down.is_set():
+        try:
+            if os.getenv("AUTO_FORGET_ENABLED") != "false":
+                if kv.acquire_lock("auto_forget", lease_seconds=300):
+                    try:
+                        print("[scheduler] Running auto_forget sweep...")
+                        res = legacy.auto_forget(kv, dry_run=False)
+                        print(f"[scheduler] auto_forget sweep completed: {res}")
+                    finally:
+                        kv.release_lock("auto_forget")
+        except Exception as e:
+            print(f"[scheduler] auto_forget loop error: {e}")
+        # Sleep in 10-second chunks so we notice _shutting_down quickly
+        for _ in range(360):  # 360 × 10s = 1 hour
+            if _shutting_down.is_set():
+                break
+            time.sleep(10)
+
+
+def _rebuild_index(kv) -> None:
+    """Rebuild the BM25/vector index from scratch in a background thread."""
+    try:
+        if kv.acquire_lock("index_rebuild", lease_seconds=600):
+            try:
+                from . import app as app_module
+
+                obs_store = getattr(app_module, "observation_store", None)
+                if obs_store is not None:
+                    count = obs_store.rebuild_index()
+                else:
+                    count = 0
+                print(f"[persistence] Rebuild completed: indexed {count} items.")
+            finally:
+                kv.release_lock("index_rebuild")
+        else:
+            print("[persistence] Another process is rebuilding the index. Skipping...")
+    except Exception as ex:
+        print(f"[persistence] Rebuild failed: {ex}")
+
+
+def start_background_workers(kv, tasks=None) -> None:
+    """Start all background daemon threads and register signal handlers.
+
+    Called once by create_app() after the DB and indexes are initialised.
+    Workers are daemon threads — they die automatically when the main process exits.
+
+    Args:
+        kv: Initialised StateKV instance.
+        tasks: Optional list of tasks to run ("index", "forget"). Defaults to running both.
+    """
+    global _kv_ref, _persistence_ref, _search_svc_ref, _obs_store_ref
+    _kv_ref = kv
+
+    from . import app as app_module
+
+    search_svc = getattr(app_module, "search_service", None)
+    obs_store = getattr(app_module, "observation_store", None)
+
+    _search_svc_ref = search_svc
+    _obs_store_ref = obs_store
+
+    if search_svc is not None:
+        _persistence_ref = search_svc._persistence
+    else:
+        _persistence_ref = None
+
+    # Register graceful shutdown signal handlers (C5.1)
+    _register_signal_handlers()
+
+    if tasks is None or "index" in tasks:
+        # Rebuild search index if empty or out of sync (Step 5)
+        bm25_size = search_svc.bm25_size if search_svc is not None else 0
+        index_empty = bm25_size == 0
+        index_in_sync = True
+        if not index_empty:
+            index_in_sync = legacy.verify_index_sync_on_boot(
+                kv, search_service=search_svc
+            )
+
+        if index_empty or not index_in_sync:
+            reason = "empty" if index_empty else "out of sync"
+            print(
+                f"[persistence] Search index is {reason}. Rebuilding in background thread..."
+            )
+            t_rebuild = threading.Thread(
+                target=_rebuild_index,
+                args=(kv,),
+                daemon=True,
+                name="index-rebuild",
+            )
+            t_rebuild.start()
+
+    if tasks is None or "forget" in tasks:
+        # Auto-forget sweep
+        t_forget = threading.Thread(
+            target=_auto_forget_loop,
+            args=(kv,),
+            daemon=True,
+            name="auto-forget",
+        )
+        t_forget.start()

agentcache_core-0.9.9.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agentcache-core
+Version: 0.9.9
+Summary: A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite
+Author-email: Yashwant K <yashwantk0303@gmail.com>
+Maintainer-email: Yashwant K <yashwantk0303@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Yashwant00CR7/agentcache
+Project-URL: Repository, https://github.com/Yashwant00CR7/agentcache.git
+Project-URL: Bug Tracker, https://github.com/Yashwant00CR7/agentcache/issues
+Project-URL: Documentation, https://github.com/Yashwant00CR7/agentcache#readme
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=3.0.0
+Requires-Dist: flask-sock>=0.7.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: huggingface_hub>=0.20.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: local-embeddings
+Requires-Dist: sentence-transformers>=2.7.0; extra == "local-embeddings"
+Dynamic: license-file
+
+# agentcache
+
+A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite.
+
+`agentcache` gives coding agents (Claude Code, Cursor, Cline, Kiro, Antigravity, …) a persistent, searchable memory of what happened in a project — observations, sessions, long-term memories, and a folder-scoped knowledge graph — with hybrid BM25 + vector search, WebSocket live updates, and a Model Context Protocol (MCP) stdio bridge.
+
+- **Server:** Flask + `flask-sock` (REST + WebSocket) on a single port
+- **Storage:** SQLite in WAL mode (zero external services)
+- **Search:** BM25 + optional local embeddings (`sentence-transformers`) or Hugging Face inference
+- **MCP:** stdio bridge so any MCP-compatible client can `observe` / `remember` / `search` natively
+- **CLI:** `agentcache serve|worker|migrate|export|context|connect`
+
+Status: **Beta** (`Development Status :: 4 - Beta`). API is stable enough for daily use; internals may still shift before 1.0.
+
+---
+
+## Install
+
+```bash
+pip install agentcache-core
+```
+
+The package installs as `agentcache-core` on PyPI but imports and runs as `agentcache` (`import agentcache`, `agentcache serve`). The plain `agentcache` name on PyPI belongs to an unrelated project.
+
+With optional local embeddings (adds `sentence-transformers`, ~1 GB of model weights on first use):
+
+```bash
+pip install "agentcache-core[local-embeddings]"
+```
+
+Requires Python 3.10+.
+
+---
+
+## Quickstart
+
+Start the server:
+
+```bash
+agentcache serve --port 3111
+```
+
+Record an observation (any HTTP client works):
+
+```bash
+curl -X POST http://localhost:3111/agentcache/observe \
+  -H "Content-Type: application/json" \
+  -d '{
+        "folderPath": "/abs/path/to/project",
+        "agentId": "coder-1",
+        "text": "Refactored auth into a decorator; see routes/auth.py",
+        "type": "refactor"
+      }'
+```
+
+Search across a folder:
+
+```bash
+curl "http://localhost:3111/agentcache/folder/observations?folderPath=/abs/path/to/project&q=auth"
+```
+
+Health check:
+
+```bash
+curl http://localhost:3111/agentcache/health
+```
+
+Generate a live context file for your IDE:
+
+```bash
+cd /abs/path/to/project
+agentcache context --watch     # writes .agentcache_context.md and re-writes on change
+```
+
+---
+
+## Programmatic use
+
+```python
+from agentcache import create_app, StateKV, remember
+
+app = create_app()                 # Flask app, ready for WSGI or app.run()
+kv  = StateKV()                    # direct KV access to the SQLite store
+remember(kv, {"title": "auth decorator", "content": "…", "agentId": "coder-1"})
+```
+
+Top-level exports: `create_app`, `StateKV`, `KV`, `ObservationStore`, `ObservationEvents`, `SearchService`, `remember`, `folder_graph_build`, `health_check`, `run_connect`.
+
+---
+
+## Wire it into your agent
+
+```bash
+agentcache connect claude-code    # or: cursor, cline, kiro, antigravity, codex
+agentcache connect --all          # detect and wire every supported client
+```
+
+This registers the MCP stdio bridge (`agentcache.mcp_stdio`) and, with `--with-hooks`, installs workspace hook blocks that call `/agentcache/observe` on file events.
+
+---
+
+## Auth
+
+Set `AGENTCACHE_SECRET` to require a shared secret on write routes:
+
+```bash
+export AGENTCACHE_SECRET=your-long-random-string
+agentcache serve
+```
+
+Clients send it via `Authorization: Bearer <secret>` or `?secret=<secret>`. Unset = open (fine for `localhost`; **do not** expose an unauthenticated instance).
+
+---
+
+## Deployment
+
+`Dockerfile` and `docker-compose.yml` are included. For multi-worker WSGI (Gunicorn + workers), run the server without background threads and use a dedicated worker process:
+
+```bash
+agentcache serve --no-workers                    # web tier
+agentcache worker --tasks=index,forget           # sidecar
+```
+
+Details and the ongoing hardening plan live in [`docs/publishing_roadmap.md`](docs/publishing_roadmap.md).
+
+---
+
+## Compatibility notes
+
+- Routes are dual-mounted at both `/agentcache/*` and `/agentmemory/*` for backward compatibility with the previous package name.
+- `agentcache.legacy` is a thin re-export shim retained for callers that imported from the pre-split module layout. It will be removed in **1.0** — migrate imports to `agentcache.core.*` when convenient. See [`docs/adr/`](docs/adr/) for the split rationale.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Yashwant00CR7/agentcache
+cd agentcache
+pip install -e ".[dev,local-embeddings]"
+
+pytest                     # test suite
+ruff check .               # lint
+ruff format .              # format
+python -m build            # build sdist + wheel into dist/
+twine check dist/*         # validate metadata before upload
+```
+
+---
+
+## Links
+
+- **Source:** https://github.com/Yashwant00CR7/agentcache
+- **Issues:** https://github.com/Yashwant00CR7/agentcache/issues
+- **License:** MIT — see [LICENSE](LICENSE)

agentcache_core-0.9.9.dist-info/RECORD

@@ -0,0 +1,52 @@
+agentcache/__init__.py,sha256=3eP0w4CraxlOxO4CXsv9uRl7y7Kg3_vE8ddTyOlpajc,591
+agentcache/app.py,sha256=7nXvkLXgVdyA0nViZYTV9ZR_DABbmiC60ASdz_c9oNc,11229
+agentcache/cli.py,sha256=RfSNZc7EsaTscuMwe7CAYO08Yz0K02uwpU4evevRF2Y,11179
+agentcache/connect.py,sha256=u7_Lta-HBBzJzNYTd7xOx1bSbhiWNp64bJSG9NKMi18,26199
+agentcache/db.py,sha256=udrasWFSrYFUdmIj0mVwvaBiWsIpk1Bvrwy54ifJ_O8,13476
+agentcache/import_data.py,sha256=5d3oPOHqDOeK8rISCb92UiynbujvRY8JbH2i85wUY-w,2886
+agentcache/legacy.py,sha256=fEqJ-nIg8ifu-hKTrMJsygaptAuE63NnompnMAtCJSw,3526
+agentcache/mcp_stdio.py,sha256=xPLSFFPFCJSvSgjpauXJNsKrWXTAbbnHmaR0T_ccqaw,3921
+agentcache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentcache/replay_import.py,sha256=bzFPgY8tadFJB7mOxANV80bTVCliZoMWb8nJGhBIgcw,22354
+agentcache/search.py,sha256=Q1WGbv2-UKTO1rFcS-MHkl0E7ugpxa2TB1MyGLsseHc,29957
+agentcache/viewer_helpers.py,sha256=IA6v_AJDzTCZfGIFXA8pkivzQZ2zvNGwY00DuT65Q04,1951
+agentcache/workers.py,sha256=gGS-yBNQTKa6LeY_AiYIZvyOu7-1IJxA0erWy29B-RY,6805
+agentcache/core/__init__.py,sha256=iC76O4gI-a-tlTMXPgbXFopJrbcxKyPvm_iLC1Elqqw,513
+agentcache/core/audit_log.py,sha256=nqz6jjRxUi-h2aKjbmPS_6LrxRxRaUmQSZ6tmkkP8OM,3065
+agentcache/core/config.py,sha256=QBQ66YuY1zqBFptYSAsBY7kzBJbUVpt574w_zljKI7w,1336
+agentcache/core/context_builder.py,sha256=1sY7DspY_ikyv6c2AWRVgbGirHwYw3iuSy7RB_knOe4,7000
+agentcache/core/graph.py,sha256=UJf_vRCxSZ18uYAXL0TL4ZvGWiKh70Dte2_OAKFzBgs,3946
+agentcache/core/image_store.py,sha256=IxzwMvG1Y1LedPqyv2Cjsokm3UP5NDp1O96hQVcDoRU,3060
+agentcache/core/infer.py,sha256=ddxmn8VZz3KWcDuUpuZDQnWaugt7G6CGdd2x_sZCav0,4288
+agentcache/core/kv_scopes.py,sha256=uMy6_uCPVvpoCXy0lkyjYCLCWMggCJ_BpxtpBqkyB2c,2762
+agentcache/core/lessons.py,sha256=Za0bq_0HrxNurGPIbq5ZzNfZ_L-PnjFWlJ0uv9X4f-8,8083
+agentcache/core/llm.py,sha256=Ls3TBauatnVwvqUlTKJYe4_hXcpPwln4JIvAT79Z9gs,23151
+agentcache/core/memory_store.py,sha256=N5wMd3ihZmJunkVFE1mpOC9x5KxnKMEs2-_STVr8Q3g,6637
+agentcache/core/observation_store.py,sha256=zezGLxPHfEx_KBQdhScOkJAaOlz2nS7hd1KkPDjhSYI,21812
+agentcache/core/privacy.py,sha256=rJ6lt2hh3HLgCcD4QpSyxxEbOJGjSpEby8J7NxSnIWw,1432
+agentcache/core/project_profile.py,sha256=bPDETYup4hHO9q3jUCXhH_04nCKyI4-nOmgGsyKlih0,22046
+agentcache/core/search_service.py,sha256=pZihTPkdkCnvDuvJZ6I7ILRWAQj4mPCHcoX0_Y7BXI4,17775
+agentcache/core/session_store.py,sha256=ClGNvfWwk-FyFCM4PBVYCTWZQKS3sSVp0ObMqa6sTnQ,12300
+agentcache/core/slots.py,sha256=gxew0cUF8Cg7IT_v3K1G93rkr86LRqzX3eoaaIK93xQ,16259
+agentcache/routes/__init__.py,sha256=UkJDqzbrw3bNiPgYwjBinhAsNKiCwLKt1r8x5XV9TEo,907
+agentcache/routes/_deps.py,sha256=K6eQ4tfvjyFvXbIMIk2GIkPpvtxJaKVdcv-CSOqUk70,1328
+agentcache/routes/auth.py,sha256=V55bRbPVdvGWmGyDRUWa1KvqSjPLPqKUBCSPOmA6y1U,2084
+agentcache/routes/graph.py,sha256=3coYit-h5EV_DSpSe63wunFzy1z1DmNADErX6bAOSZ0,2718
+agentcache/routes/health.py,sha256=uyRTY1ErO8QiMGbtrPFvsQSoxt6pz4nPSgBRvUCBvmg,5697
+agentcache/routes/mcp.py,sha256=6N0367oOSYVpCDizyzbgLsbKCcomtWeh2Dx4CxylPSM,24386
+agentcache/routes/memories.py,sha256=OWj0Idk-pmsYRWVQFqvWbi0F5fYMqS29r3y1QLcwDlE,4045
+agentcache/routes/migration.py,sha256=UujsgPUbiARfhTTdN5xf29rkoZQdL4Q6PavxJZhk-P0,899
+agentcache/routes/observations.py,sha256=AVd1G-BAnTJjOCmgjqig2nNXY2ENxmDQ16Ul4CsQ1Ds,8377
+agentcache/routes/search.py,sha256=jFyQqgOkXnMxVT2gwrk5Ri-lbQvVBD918_mv9IswE08,2453
+agentcache/storage/__init__.py,sha256=m2WcbQ0L0lbpY3EL9pW5D8Kptq2KR7Q28F_pMCt9XvQ,937
+agentcache/storage/images.py,sha256=1eclOAEyDfIHclpG293c9TfX_SCsT3c5LonmoHsTb0U,3051
+agentcache/storage/paths.py,sha256=cYLTLgmvrpD0uaJZ_xAjDOBXn1342YRsenUlNpWcpDs,3745
+agentcache/storage/scopes.py,sha256=Zv1W7XdoScjMvfD0WBVtwTMmL2fioga6Z7fdYilGMqQ,174
+agentcache/viewer/favicon.svg,sha256=kAnAwcC26JWar46tMtTYMifvAz2B8dW4eJfwGaZhpmg,249
+agentcache/viewer/index.html,sha256=LcgxQan8roOoiTCxqnj9UzGxTdIBdWxxfe-A4abV32w,182896
+agentcache_core-0.9.9.dist-info/licenses/LICENSE,sha256=dsjUmrQiFqJTP2A_uvogob9xtW3hNqQBvlLaA03MASw,10764
+agentcache_core-0.9.9.dist-info/METADATA,sha256=1Yoc4mTjltjTKM-C07yuCshgQF0GAaSScWr1GUQlGsM,6531
+agentcache_core-0.9.9.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agentcache_core-0.9.9.dist-info/entry_points.txt,sha256=e_uwu1g4TggwGvTundDtHH5d_SYm_EQ5liaPpwd6N9w,51
+agentcache_core-0.9.9.dist-info/top_level.txt,sha256=l1iTOQb85Sum3076_Ej_JkDWmiB2ZnF07bgHfu4uE3E,11
+agentcache_core-0.9.9.dist-info/RECORD,,

agentcache_core-0.9.9.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentcache_core-0.9.9.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentcache = agentcache.cli:main