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 +2 -0
- recallhook/api.py +72 -0
- recallhook/cli.py +162 -0
- recallhook/config.py +56 -0
- recallhook/events.py +68 -0
- recallhook/gateway.py +179 -0
- recallhook/hook.py +35 -0
- recallhook/inject.py +116 -0
- recallhook/install.py +134 -0
- recallhook/memory.py +218 -0
- recallhook/security.py +20 -0
- recallhook/supervisor.py +90 -0
- recallhook/ui.py +113 -0
- recallhook-0.1.0.dist-info/METADATA +155 -0
- recallhook-0.1.0.dist-info/RECORD +18 -0
- recallhook-0.1.0.dist-info/WHEEL +4 -0
- recallhook-0.1.0.dist-info/entry_points.txt +2 -0
- recallhook-0.1.0.dist-info/licenses/LICENSE +21 -0
recallhook/__init__.py
ADDED
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
|