recallhook 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
recallhook/__init__.py ADDED
@@ -0,0 +1,2 @@
1
+ """mem0 long-term memory, local via Ollama, in front of the Headroom proxy."""
2
+ __version__ = "0.1.0"
recallhook/api.py ADDED
@@ -0,0 +1,72 @@
1
+ """JSON API used by the Claude Code hook and the dashboard."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ from collections import OrderedDict
6
+
7
+ from fastapi import APIRouter, Request
8
+ from pydantic import BaseModel
9
+
10
+ from .inject import clean_prompt, format_block, is_automated, is_question, looks_durable, recall_query
11
+ from .security import make_guard
12
+
13
+
14
+ class PromptIn(BaseModel):
15
+ text: str
16
+ user: str | None = None
17
+ session: str | None = None
18
+
19
+
20
+ def build_api_router(cfg, memory) -> APIRouter:
21
+ r = APIRouter(prefix="/_recallhook/api")
22
+ guard = make_guard(cfg)
23
+ # memories already injected per Claude session: injecting the same fact on every
24
+ # prompt would just burn tokens, since earlier injections stay in the transcript.
25
+ seen: OrderedDict[str, set[str]] = OrderedDict()
26
+
27
+ @r.post("/prompt")
28
+ async def prompt(request: Request, body: PromptIn):
29
+ """One round trip for the hook: recall relevant memories, then queue capture."""
30
+ guard(request, mutating=True)
31
+ user = body.user or cfg.user_id
32
+ if is_automated(body.text): # app/harness messages, not the user
33
+ return {"block": "", "hits": 0}
34
+ text = clean_prompt(body.text)
35
+ if len(text) < cfg.min_chars or text.startswith("/"):
36
+ return {"block": "", "hits": 0}
37
+ items = await memory.recall(recall_query(text), user, source="hook") if cfg.inject else []
38
+ items = items or []
39
+ sid = body.session or ""
40
+ known = seen.setdefault(sid, set())
41
+ seen.move_to_end(sid)
42
+ while len(seen) > 200:
43
+ seen.popitem(last=False)
44
+ fresh = [i for i in items if i["id"] not in known]
45
+ known.update(i["id"] for i in fresh)
46
+ if not is_question(text) and looks_durable(text):
47
+ memory.capture(text, user)
48
+ return {"block": format_block([i["memory"] for i in fresh]) if fresh else "", "hits": len(fresh)}
49
+
50
+ @r.get("/activity")
51
+ async def activity(request: Request, limit: int = 40):
52
+ guard(request)
53
+ return memory.events.recent(min(limit, 200))
54
+
55
+ @r.get("/series")
56
+ async def series(request: Request, days: int = 14):
57
+ guard(request)
58
+ return memory.events.series(min(days, 90))
59
+
60
+ @r.get("/summary")
61
+ async def summary(request: Request):
62
+ guard(request)
63
+ t = memory.events.totals()
64
+ try:
65
+ t["memories"] = len(await asyncio.to_thread(memory.list_all, cfg.user_id))
66
+ except Exception: # noqa: BLE001
67
+ t["memories"] = None
68
+ t["capture_queue"] = memory._q.qsize()
69
+ t["failures"] = memory.stats.get("search_failures", 0)
70
+ return t
71
+
72
+ return r
recallhook/cli.py ADDED
@@ -0,0 +1,162 @@
1
+ """recallhook serve | doctor | install | uninstall | hooks | route | status | ui"""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import json
6
+ import logging
7
+ import sys
8
+ import urllib.request
9
+
10
+ from .config import Config
11
+
12
+
13
+ def _parser() -> argparse.ArgumentParser:
14
+ d = Config()
15
+ p = argparse.ArgumentParser("recallhook", description="mem0 memory in front of the Headroom proxy")
16
+ sub = p.add_subparsers(dest="cmd", required=True)
17
+ for name in ("serve", "doctor"):
18
+ s = sub.add_parser(name)
19
+ s.add_argument("--upstream", default=d.upstream, help="Headroom proxy URL")
20
+ s.add_argument("--fallback", default=d.fallback,
21
+ help="where to send requests if Headroom refuses connections ('' disables)")
22
+ s.add_argument("--host", default=d.host)
23
+ s.add_argument("--port", type=int, default=d.port)
24
+ s.add_argument("--ollama-url", default=d.ollama_url)
25
+ s.add_argument("--llm-model", default=d.llm_model, help="extraction model")
26
+ s.add_argument("--embed-model", default=d.embed_model)
27
+ s.add_argument("--num-ctx", type=int, default=d.num_ctx)
28
+ s.add_argument("--store", dest="store_path", default=d.store_path)
29
+ s.add_argument("--user-id", default=d.user_id)
30
+ s.add_argument("--top-k", type=int, default=d.top_k)
31
+ s.add_argument("--min-score", type=float, default=d.min_score)
32
+ s.add_argument("--no-write", dest="write", action="store_false", default=d.write,
33
+ help="recall only; never store anything")
34
+ s.add_argument("--no-inject", dest="inject", action="store_false", default=d.inject,
35
+ help="store only; never inject memories")
36
+ if name == "serve":
37
+ s.add_argument("--spawn-headroom", action="store_true",
38
+ help="also run (and keep alive) `headroom proxy` on the upstream port")
39
+ i = sub.add_parser("install", help="start at logon (Windows) + add the Claude Code memory hook")
40
+ i.add_argument("--route-claude", action="store_true",
41
+ help="also route Claude Code traffic through the gateway (not recommended: no measured saving)")
42
+ i.add_argument("--with-headroom", action="store_true", help="also run the Headroom proxy (opt-in)")
43
+ h = sub.add_parser("hooks", help="add or remove the Claude Code memory hook")
44
+ h.add_argument("state", choices=["on", "off"])
45
+ sub.add_parser("hook", help="(internal) the UserPromptSubmit hook; reads the event from stdin")
46
+ sub.add_parser("uninstall", help="remove autostart + Claude routing, stop the processes")
47
+ r = sub.add_parser("route", help="turn Claude Code routing on or off")
48
+ r.add_argument("state", choices=["on", "off"])
49
+ sub.add_parser("status")
50
+ sub.add_parser("ui", help="open the memory dashboard in your browser")
51
+ return p
52
+
53
+
54
+ def _get(url: str) -> dict:
55
+ with urllib.request.urlopen(url, timeout=5) as r:
56
+ return json.loads(r.read())
57
+
58
+
59
+ def doctor(cfg: Config) -> int:
60
+ ok = True
61
+
62
+ def check(label: str, fn) -> None:
63
+ nonlocal ok
64
+ try:
65
+ print(f"[ok] {label}: {fn()}")
66
+ except Exception as e: # noqa: BLE001
67
+ ok = False
68
+ print(f"[FAIL] {label}: {type(e).__name__}: {e}")
69
+
70
+ def models() -> str:
71
+ have = {m["name"] for m in _get(cfg.ollama_url + "/api/tags")["models"]}
72
+ missing = [m for m in (cfg.llm_model, cfg.embed_model) if m not in have]
73
+ if missing:
74
+ raise RuntimeError(f"not pulled: {missing} (run `ollama pull <name>`)")
75
+ return f"{cfg.llm_model}, {cfg.embed_model}"
76
+
77
+ check("ollama models", models)
78
+ try: # the Headroom proxy is optional, so its absence is not a failure
79
+ code = urllib.request.urlopen(cfg.upstream.rstrip("/") + "/livez", timeout=3).status
80
+ print(f"[ok] headroom proxy (optional): {cfg.upstream} -> HTTP {code}")
81
+ except Exception: # noqa: BLE001
82
+ print("[--] headroom proxy (optional): not running")
83
+ check("gateway", lambda: _get(f"http://127.0.0.1:{cfg.port}/_recallhook/health")["stats"])
84
+ return 0 if ok else 1
85
+
86
+
87
+ def _setup_logging(cfg: Config) -> None:
88
+ """pythonw has no stdout/stderr, so always log to a file there."""
89
+ fmt = "%(asctime)s %(levelname)s %(message)s"
90
+ if sys.stdout is None or sys.stderr is None:
91
+ logdir = cfg.home / "logs"
92
+ logdir.mkdir(parents=True, exist_ok=True)
93
+ path = logdir / "gateway.log"
94
+ if path.exists() and path.stat().st_size > 5_000_000:
95
+ path.replace(logdir / "gateway.old.log")
96
+ sys.stdout = sys.stderr = open(path, "a", buffering=1, encoding="utf-8")
97
+ logging.basicConfig(level=logging.INFO, format=fmt, stream=sys.stderr)
98
+
99
+
100
+ def serve(cfg: Config, spawn: bool) -> int:
101
+ import uvicorn
102
+
103
+ from .gateway import create_app
104
+
105
+ _setup_logging(cfg)
106
+ if spawn:
107
+ from .supervisor import Supervisor, healthy
108
+
109
+ sup = Supervisor(cfg.upstream, cfg.home / "logs" / "headroom.log")
110
+ if not healthy(cfg.upstream):
111
+ sup.spawn()
112
+ sup.start()
113
+ # One process / one worker: local Qdrant takes a file lock on the store.
114
+ uvicorn.run(create_app(cfg), host=cfg.host, port=cfg.port, workers=1, log_level="info",
115
+ log_config=None)
116
+ return 0
117
+
118
+
119
+ def main(argv: list[str] | None = None) -> int:
120
+ a = _parser().parse_args(argv)
121
+ cfg = Config()
122
+ for k in vars(cfg):
123
+ if hasattr(a, k):
124
+ setattr(cfg, k, getattr(a, k))
125
+ from . import install as ins
126
+
127
+ if a.cmd in ("serve", "doctor"):
128
+ return doctor(cfg) if a.cmd == "doctor" else serve(cfg, a.spawn_headroom)
129
+ if a.cmd == "hook":
130
+ from .hook import run
131
+
132
+ return run(cfg.port)
133
+ if a.cmd == "hooks":
134
+ print(ins.install_hook(a.state == "on"))
135
+ return 0
136
+ if a.cmd == "install":
137
+ print(ins.install_task("serve --spawn-headroom" if a.with_headroom else "serve"))
138
+ print(ins.install_hook(True))
139
+ if a.route_claude:
140
+ print(ins.route_claude(True, cfg.port))
141
+ return 0
142
+ if a.cmd == "route":
143
+ print(ins.route_claude(a.state == "on", cfg.port))
144
+ return 0
145
+ if a.cmd == "uninstall":
146
+ print(ins.route_claude(False, cfg.port))
147
+ print(ins.install_hook(False))
148
+ print(ins.remove_task())
149
+ print("stopped pids:", ins.kill_ports(cfg.port, int(cfg.upstream.rsplit(":", 1)[-1])) or "none")
150
+ return 0
151
+ if a.cmd == "status":
152
+ return doctor(cfg)
153
+ if a.cmd == "ui":
154
+ import webbrowser
155
+
156
+ webbrowser.open(f"http://127.0.0.1:{cfg.port}/_recallhook/ui")
157
+ return 0
158
+ return 1
159
+
160
+
161
+ if __name__ == "__main__":
162
+ raise SystemExit(main())
recallhook/config.py ADDED
@@ -0,0 +1,56 @@
1
+ """Runtime configuration, resolved from defaults < environment < CLI flags."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ from dataclasses import dataclass, field, fields
6
+ from pathlib import Path
7
+
8
+
9
+ def _env(name: str, default, cast=str):
10
+ raw = os.environ.get(f"RECALLHOOK_{name}")
11
+ return default if raw is None else cast(raw)
12
+
13
+
14
+ def _bool(v: str) -> bool:
15
+ return v.strip().lower() in {"1", "true", "yes", "on"}
16
+
17
+
18
+ @dataclass
19
+ class Config:
20
+ # Where requests are forwarded: normally the Headroom proxy.
21
+ upstream: str = field(default_factory=lambda: _env("UPSTREAM", "http://127.0.0.1:8787"))
22
+ # Used only when the upstream (Headroom) refuses connections, so Claude keeps working.
23
+ fallback: str = field(default_factory=lambda: _env("FALLBACK", "https://api.anthropic.com"))
24
+ host: str = field(default_factory=lambda: _env("HOST", "127.0.0.1"))
25
+ port: int = field(default_factory=lambda: _env("PORT", 8788, int))
26
+
27
+ # Local models served by Ollama.
28
+ ollama_url: str = field(default_factory=lambda: _env("OLLAMA_URL", "http://localhost:11434"))
29
+ llm_model: str = field(default_factory=lambda: _env("LLM_MODEL", "qwen3:8b"))
30
+ embed_model: str = field(default_factory=lambda: _env("EMBED_MODEL", "nomic-embed-text:latest"))
31
+ embed_dims: int = field(default_factory=lambda: _env("EMBED_DIMS", 768, int))
32
+
33
+ # Ollama tuning. mem0 exposes none of these, so we inject them per request.
34
+ num_ctx: int = field(default_factory=lambda: _env("NUM_CTX", 4096, int))
35
+ keep_alive: str = field(default_factory=lambda: _env("KEEP_ALIVE", "30m"))
36
+ embed_on_cpu: bool = field(default_factory=lambda: _env("EMBED_ON_CPU", True, _bool))
37
+
38
+ store_path: str = field(
39
+ default_factory=lambda: _env("STORE", str(Path.home() / ".recallhook"))
40
+ )
41
+ user_id: str = field(default_factory=lambda: _env("USER_ID", "default"))
42
+
43
+ top_k: int = field(default_factory=lambda: _env("TOP_K", 5, int))
44
+ min_score: float = field(default_factory=lambda: _env("MIN_SCORE", 0.5, float))
45
+ search_timeout: float = field(default_factory=lambda: _env("SEARCH_TIMEOUT", 3.0, float))
46
+ inject: bool = field(default_factory=lambda: _env("INJECT", True, _bool))
47
+ write: bool = field(default_factory=lambda: _env("WRITE", True, _bool))
48
+ queue_size: int = field(default_factory=lambda: _env("QUEUE_SIZE", 16, int))
49
+ min_chars: int = 20 # ignore trivially short user turns ("ok", "continue")
50
+
51
+ @property
52
+ def home(self) -> Path:
53
+ return Path(self.store_path).expanduser()
54
+
55
+ def public(self) -> dict:
56
+ return {f.name: getattr(self, f.name) for f in fields(self)}
recallhook/events.py ADDED
@@ -0,0 +1,68 @@
1
+ """Small persistent activity log (SQLite) that feeds the dashboard.
2
+
3
+ Stores counts, latencies and short snippets of memories that were recalled/stored.
4
+ It never stores the user's prompt text."""
5
+ from __future__ import annotations
6
+
7
+ import sqlite3
8
+ import threading
9
+ import time
10
+ from pathlib import Path
11
+
12
+ KEEP_DAYS = 90
13
+
14
+
15
+ class EventLog:
16
+ def __init__(self, path: Path | str):
17
+ Path(path).parent.mkdir(parents=True, exist_ok=True)
18
+ self._db = sqlite3.connect(str(path), check_same_thread=False)
19
+ self._lock = threading.Lock()
20
+ with self._lock:
21
+ self._db.execute("""CREATE TABLE IF NOT EXISTS events(
22
+ ts REAL, kind TEXT, source TEXT, hits INTEGER, ms INTEGER, tokens INTEGER, detail TEXT)""")
23
+ self._db.execute("DELETE FROM events WHERE ts < ?", (time.time() - KEEP_DAYS * 86400,))
24
+ self._db.commit()
25
+
26
+ def add(self, kind: str, source: str = "", hits: int = 0, ms: int = 0,
27
+ tokens: int = 0, detail: str = "") -> None:
28
+ with self._lock:
29
+ self._db.execute("INSERT INTO events VALUES(?,?,?,?,?,?,?)",
30
+ (time.time(), kind, source, hits, ms, tokens, detail[:400]))
31
+ self._db.commit()
32
+
33
+ def recent(self, limit: int = 40) -> list[dict]:
34
+ with self._lock:
35
+ rows = self._db.execute(
36
+ "SELECT ts,kind,source,hits,ms,tokens,detail FROM events ORDER BY ts DESC LIMIT ?",
37
+ (limit,)).fetchall()
38
+ return [dict(zip(("ts", "kind", "source", "hits", "ms", "tokens", "detail"), r)) for r in rows]
39
+
40
+ def series(self, days: int = 14) -> list[dict]:
41
+ since = time.time() - days * 86400
42
+ with self._lock:
43
+ rows = self._db.execute(
44
+ """SELECT date(ts,'unixepoch','localtime') d, kind, COUNT(*), COALESCE(SUM(hits),0),
45
+ COALESCE(SUM(tokens),0) FROM events WHERE ts>=? GROUP BY d, kind""",
46
+ (since,)).fetchall()
47
+ out: dict[str, dict] = {}
48
+ for d, kind, n, hits, tokens in rows:
49
+ row = out.setdefault(d, {"day": d, "recall": 0, "stored": 0, "tokens": 0})
50
+ if kind == "recall":
51
+ row["recall"] += n
52
+ row["tokens"] += tokens
53
+ elif kind == "stored":
54
+ row["stored"] += hits # hits = memories created
55
+ return [out[k] for k in sorted(out)]
56
+
57
+ def totals(self) -> dict:
58
+ with self._lock:
59
+ r = self._db.execute(
60
+ """SELECT COUNT(*), COALESCE(SUM(hits>0),0), COALESCE(AVG(ms),0), COALESCE(SUM(tokens),0)
61
+ FROM events WHERE kind='recall'""").fetchone()
62
+ s = self._db.execute("SELECT COALESCE(SUM(hits),0) FROM events WHERE kind='stored'").fetchone()
63
+ t = self._db.execute(
64
+ "SELECT COUNT(*) FROM events WHERE kind='recall' AND ts>=?",
65
+ (time.mktime(time.localtime()[:3] + (0, 0, 0, 0, 0, -1)),)).fetchone()
66
+ n = r[0]
67
+ return {"recalls": n, "recalls_today": t[0], "hit_rate": round(100 * r[1] / n) if n else 0,
68
+ "avg_ms": round(r[2]), "tokens_injected": r[3], "memories_created": s[0]}
recallhook/gateway.py ADDED
@@ -0,0 +1,179 @@
1
+ """HTTP gateway: client -> (this: mem0 recall + capture) -> Headroom proxy -> provider.
2
+
3
+ Everything that is not a chat request is streamed through untouched, and any
4
+ memory failure falls back to forwarding the request unchanged.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import asyncio
9
+ import contextlib
10
+ import json
11
+ import logging
12
+ from collections import OrderedDict
13
+
14
+ import httpx
15
+ from fastapi import FastAPI, Request
16
+ from fastapi.responses import JSONResponse, StreamingResponse
17
+ from starlette.background import BackgroundTask
18
+
19
+ from .config import Config
20
+ from .inject import (append_block, format_block, is_memory_path, is_side_request,
21
+ text_key, user_turns)
22
+ from .memory import MemoryService
23
+
24
+ log = logging.getLogger("recallhook")
25
+
26
+ HOP = {"connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te",
27
+ "trailers", "transfer-encoding", "upgrade"}
28
+ USER_HEADER = "x-recallhook-user"
29
+ CACHE_MAX = 512
30
+
31
+
32
+ class Gateway:
33
+ def __init__(self, cfg: Config, memory: MemoryService):
34
+ self.cfg, self.memory = cfg, memory
35
+ # text-hash -> injected memories. Re-injecting the *same* block into the
36
+ # same user turn on every later request keeps the conversation prefix
37
+ # byte-identical, so provider prompt caching (and Headroom's cache mode)
38
+ # keeps working.
39
+ self.fallbacks = 0
40
+ self._recalled: OrderedDict[str, list[str]] = OrderedDict()
41
+ self._written: set[str] = set()
42
+
43
+ def _remember(self, key: str, memories: list[str]) -> None:
44
+ self._recalled[key] = memories
45
+ self._recalled.move_to_end(key)
46
+ while len(self._recalled) > CACHE_MAX:
47
+ self._recalled.popitem(last=False)
48
+
49
+ async def transform(self, body: dict, user_id: str) -> str | None:
50
+ """Inject recalled memories in place. Returns text to capture once the
51
+ upstream call succeeds (see `commit`), or None."""
52
+ if is_side_request(body):
53
+ return None
54
+ turns = user_turns(body)
55
+ if not turns:
56
+ return None
57
+ msgs = body["messages"]
58
+ newest = turns[-1][0]
59
+ for idx, text in turns:
60
+ key = text_key(text)
61
+ if key not in self._recalled and idx == newest and self.cfg.inject:
62
+ found = await self.memory.search(text[:1000], user_id)
63
+ if found is not None: # None = lookup failed; do not cache
64
+ self._remember(key, found)
65
+ if self._recalled.get(key):
66
+ append_block(msgs[idx], format_block(self._recalled[key]))
67
+ newest_text = turns[-1][1]
68
+ if (self.cfg.write and text_key(newest_text) not in self._written
69
+ and len(newest_text) >= self.cfg.min_chars):
70
+ return newest_text
71
+ return None
72
+
73
+ def commit(self, text: str, user_id: str) -> None:
74
+ """Queue a capture. Called only after a 2xx upstream response, so failed
75
+ or rejected requests never leave memories behind."""
76
+ key = text_key(text)
77
+ if key not in self._written:
78
+ self._written.add(key)
79
+ self.memory.submit(text, user_id)
80
+
81
+
82
+ def create_app(cfg: Config, memory: MemoryService | None = None,
83
+ transport: httpx.AsyncBaseTransport | None = None,
84
+ fallback_transport: httpx.AsyncBaseTransport | None = None) -> FastAPI:
85
+ memory = memory or MemoryService(cfg)
86
+ gw = Gateway(cfg, memory)
87
+
88
+ @contextlib.asynccontextmanager
89
+ async def lifespan(app: FastAPI):
90
+ memory.start()
91
+ app.state.http = httpx.AsyncClient(
92
+ base_url=cfg.upstream.rstrip("/"), transport=transport,
93
+ timeout=httpx.Timeout(None, connect=10.0), follow_redirects=False)
94
+ app.state.fallback = (httpx.AsyncClient(
95
+ base_url=cfg.fallback.rstrip("/"), transport=fallback_transport, timeout=httpx.Timeout(None, connect=10.0))
96
+ if cfg.fallback else None)
97
+ warm = asyncio.create_task(asyncio.to_thread(_safe_warm, memory))
98
+ try:
99
+ yield
100
+ finally:
101
+ warm.cancel()
102
+ await app.state.http.aclose()
103
+ if app.state.fallback:
104
+ await app.state.fallback.aclose()
105
+
106
+ app = FastAPI(lifespan=lifespan, docs_url=None, redoc_url=None, openapi_url=None)
107
+ app.state.gateway = gw
108
+ from .api import build_api_router
109
+ from .ui import build_router
110
+ app.include_router(build_router(cfg, memory))
111
+ app.include_router(build_api_router(cfg, memory))
112
+
113
+ @app.get("/_recallhook/health")
114
+ async def health():
115
+ return {"ok": True, "upstream": cfg.upstream, "llm": cfg.llm_model,
116
+ "embedder": cfg.embed_model, "stats": memory.stats,
117
+ "inject": cfg.inject, "write": cfg.write, "fallbacks": gw.fallbacks}
118
+
119
+ @app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"])
120
+ async def forward(request: Request, path: str):
121
+ raw = await request.body()
122
+ user_id = request.headers.get(USER_HEADER) or cfg.user_id
123
+ headers = {k: v for k, v in request.headers.items()
124
+ if k.lower() not in HOP | {"host", "content-length", USER_HEADER}}
125
+ capture: str | None = None
126
+ if request.method == "POST" and is_memory_path(request.url.path):
127
+ try:
128
+ body = json.loads(raw)
129
+ except ValueError:
130
+ body = None
131
+ if isinstance(body, dict):
132
+ try:
133
+ before = _compact(body)
134
+ capture = await gw.transform(body, user_id)
135
+ after = _compact(body)
136
+ if after != before: # untouched requests are forwarded byte-for-byte
137
+ raw = after.encode("utf-8")
138
+ except Exception as e: # noqa: BLE001 - never break the request
139
+ log.warning("transform skipped: %s", type(e).__name__)
140
+ up = None
141
+ for client in (request.app.state.http, request.app.state.fallback):
142
+ if client is None:
143
+ continue
144
+ try:
145
+ up = await client.send(client.build_request(
146
+ request.method, request.url.path, params=request.query_params,
147
+ headers=headers, content=raw), stream=True)
148
+ break
149
+ except (httpx.ConnectError, httpx.ConnectTimeout) as e:
150
+ # Only connection failures fall through: nothing was sent, so a retry
151
+ # against the fallback can never double-bill a request.
152
+ if client is not request.app.state.http:
153
+ return JSONResponse({"error": f"unreachable: {type(e).__name__}"}, status_code=502)
154
+ gw.fallbacks += 1
155
+ except httpx.HTTPError as e:
156
+ return JSONResponse({"error": f"upstream error: {type(e).__name__}"}, status_code=502)
157
+ if up is None:
158
+ return JSONResponse({"error": "upstream unreachable"}, status_code=502)
159
+ if capture and up.status_code < 300:
160
+ gw.commit(capture, user_id)
161
+ out = {k: v for k, v in up.headers.items() if k.lower() not in HOP}
162
+ # aiter_raw: bytes are forwarded exactly as sent, so the upstream
163
+ # content-encoding / content-length headers stay truthful.
164
+ return StreamingResponse(up.aiter_raw(), status_code=up.status_code, headers=out,
165
+ background=BackgroundTask(up.aclose))
166
+
167
+ return app
168
+
169
+
170
+ def _compact(body: dict) -> str:
171
+ return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
172
+
173
+
174
+ def _safe_warm(memory: MemoryService) -> None:
175
+ try:
176
+ memory.warm()
177
+ log.info("mem0 ready")
178
+ except Exception as e: # noqa: BLE001
179
+ log.warning("mem0 warmup failed (will retry lazily): %s", type(e).__name__)
recallhook/hook.py ADDED
@@ -0,0 +1,35 @@
1
+ """Claude Code UserPromptSubmit hook: recall relevant memories, capture the prompt.
2
+
3
+ Stdlib only (it starts on every prompt). Fail-open: if the gateway is down or slow
4
+ it prints nothing and exits 0, so it can never block or break a prompt."""
5
+ from __future__ import annotations
6
+
7
+ import json
8
+ import os
9
+ import sys
10
+ import urllib.request
11
+
12
+ TIMEOUT = 4.0
13
+
14
+
15
+ def run(port: int | None = None) -> int:
16
+ try:
17
+ data = json.loads(sys.stdin.buffer.read().decode("utf-8", "replace") or "{}")
18
+ except ValueError:
19
+ return 0
20
+ if data.get("hook_event_name") != "UserPromptSubmit":
21
+ return 0
22
+ port = port or int(os.environ.get("RECALLHOOK_PORT", "8788"))
23
+ body = json.dumps({"text": data.get("prompt", ""), "session": data.get("session_id")}).encode("utf-8")
24
+ req = urllib.request.Request(
25
+ f"http://127.0.0.1:{port}/_recallhook/api/prompt", data=body,
26
+ headers={"content-type": "application/json", "x-hm-client": "claude-hook"})
27
+ try:
28
+ with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
29
+ block = json.loads(r.read()).get("block", "")
30
+ except Exception: # noqa: BLE001 - gateway down/slow: just skip memory
31
+ return 0
32
+ if block:
33
+ out = {"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": block}}
34
+ sys.stdout.buffer.write(json.dumps(out, ensure_ascii=False).encode("utf-8"))
35
+ return 0