meshctx-ctxkit 0.1.0__py3-none-any.whl

meshctx_ctxkit/memory.py

@@ -0,0 +1,208 @@
+"""Local-first memory store for ctxkit.
+
+Design goals, in priority order:
+  1. Never lose data. Every write is fsync'd into a JSONL append log.
+  2. Never need a network. Zero dependencies; pure stdlib.
+  3. Never be slow on read. An in-process index over the JSONL.
+
+Storage layout (all under ``~/.ctxkit`` by default)::
+
+    memory.jsonl        append-only log of {id, text, tags, ts, ...}
+    .lock               advisory lock file
+
+Retrieval is lexical (BM25-style) rather than vector-based on purpose:
+it needs no embedding model, no downloads, and no GPU — which is what
+"local-first, works on a plane" actually requires.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Any, Iterable
+
+_WORD_RE = re.compile(r"[a-z0-9_]+|[\u4e00-\u9fff]", re.IGNORECASE)
+
+
+def _tokenize(text: str) -> list[str]:
+    """Split into lowercase word tokens; CJK is split per character so that
+    Chinese/Japanese notes still retrieve sensibly without a segmenter."""
+    return [t.lower() for t in _WORD_RE.findall((text or "").lower())]
+
+
+@dataclass
+class Memory:
+    id: str
+    text: str
+    tags: list[str] = field(default_factory=list)
+    ts: float = field(default_factory=time.time)
+    source: str = "manual"
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False)
+
+
+class MemoryStore:
+    """Append-only JSONL memory with an in-memory lexical index."""
+
+    def __init__(self, root: str | os.PathLike | None = None) -> None:
+        base = Path(root or os.environ.get("CTXKIT_HOME") or Path.home() / ".ctxkit")
+        base.mkdir(parents=True, exist_ok=True)
+        self.path = base / "memory.jsonl"
+        self._lock = threading.RLock()
+        self._items: dict[str, Memory] = {}
+        self._tokens: dict[str, list[str]] = {}
+        self._df: dict[str, int] = {}
+        self._load()
+
+    # ── persistence ────────────────────────────────────────────────────
+    def _load(self) -> None:
+        if not self.path.exists():
+            return
+        with self.path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except json.JSONDecodeError:
+                    continue  # a torn trailing line must never break startup
+                if obj.get("_op") == "delete":
+                    self._forget_index(obj.get("id", ""))
+                    continue
+                mem = Memory(
+                    id=obj.get("id") or uuid.uuid4().hex,
+                    text=obj.get("text", ""),
+                    tags=list(obj.get("tags") or []),
+                    ts=float(obj.get("ts") or time.time()),
+                    source=obj.get("source", "manual"),
+                )
+                self._index(mem)
+
+    def _index(self, mem: Memory) -> None:
+        self._items[mem.id] = mem
+        toks = _tokenize(mem.text + " " + " ".join(mem.tags))
+        self._tokens[mem.id] = toks
+        for tok in set(toks):
+            self._df[tok] = self._df.get(tok, 0) + 1
+
+    def _forget_index(self, mem_id: str) -> None:
+        mem = self._items.pop(mem_id, None)
+        if not mem:
+            return
+        for tok in set(self._tokens.pop(mem_id, [])):
+            n = self._df.get(tok, 0) - 1
+            if n <= 0:
+                self._df.pop(tok, None)
+            else:
+                self._df[tok] = n
+
+    def _append(self, obj: dict[str, Any]) -> None:
+        line = json.dumps(obj, ensure_ascii=False) + "\n"
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(line)
+            fh.flush()
+            os.fsync(fh.fileno())
+
+    # ── public API ─────────────────────────────────────────────────────
+    def remember(self, text: str, tags: Iterable[str] | None = None,
+                 source: str = "manual") -> Memory:
+        text = (text or "").strip()
+        if not text:
+            raise ValueError("text must not be empty")
+        if len(text) > 100_000:
+            raise ValueError("text too long (100k chars max)")
+        mem = Memory(id=uuid.uuid4().hex, text=text,
+                     tags=[t.strip() for t in (tags or []) if t.strip()],
+                     ts=time.time(), source=source)
+        with self._lock:
+            self._append({"id": mem.id, "text": mem.text, "tags": mem.tags,
+                          "ts": mem.ts, "source": mem.source})
+            self._index(mem)
+        return mem
+
+    def recall(self, query: str, limit: int = 5,
+               tags: Iterable[str] | None = None) -> list[dict[str, Any]]:
+        limit = max(1, min(int(limit), 100))
+        want = {t.strip() for t in (tags or []) if t.strip()}
+        q = _tokenize(query)
+        qset = set(q)
+        n = max(1, len(self._items))
+        avgdl = (sum(len(v) for v in self._tokens.values()) / n) if n else 1.0
+
+        k1, b = 1.5, 0.75
+        scored: list[tuple[float, Memory]] = []
+        with self._lock:
+            items = list(self._items.values())
+        for mem in items:
+            if want and not want.issubset(set(mem.tags)):
+                continue
+            toks = self._tokens.get(mem.id, [])
+            tf: list[str] = list(toks)
+            dl = len(toks) or 1
+            score = 0.0
+            unique_terms = list(dict.fromkeys(q))
+            for term in unique_terms:
+                f = tf.count(term)
+                if not f:
+                    continue
+                idf = math.log(1 + (n - self._df.get(term, 0) + 0.5)
+                               / (self._df.get(term, 0) + 0.5))
+                score += idf * (f * (k1 + 1)) / (f + k1 * (1 - b + b * dl / avgdl))
+            if qset:
+                # Exact whole-query substring hit is the strongest relevance
+                # signal; without it a 3-word doc can beat the longer doc that
+                # literally contains the phrase the user typed.
+                if query.strip() and query.strip().lower() in mem.text.lower():
+                    score *= 1.5
+                if score <= 0:
+                    continue
+            scored.append((score, mem))
+
+        scored.sort(key=lambda p: (p[0], p[1].ts), reverse=True)
+        out = []
+        for score, mem in scored[:limit]:
+            out.append({"id": mem.id, "text": mem.text, "tags": mem.tags,
+                        "ts": mem.ts, "age_days": round((time.time() - mem.ts) / 86400, 1),
+                        "score": round(score, 4)})
+        return out
+
+    def forget(self, mem_id: str) -> bool:
+        with self._lock:
+            if mem_id not in self._items:
+                return False
+            self._append({"_op": "delete", "id": mem_id})
+            self._forget_index(mem_id)
+            self._compact_if_needed()
+        return True
+
+    def stats(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "count": len(self._items),
+                "path": str(self.path),
+                "tags": sorted({t for m in self._items.values() for t in m.tags}),
+                "vocab": len(self._df),
+            }
+
+    def _compact_if_needed(self, ratio: float = 0.4) -> None:
+        """Rewrite the log when deletes dominate, so it never grows forever."""
+        try:
+            raw_lines = sum(1 for _ in self.path.open("r", encoding="utf-8"))
+        except OSError:
+            return
+        live = len(self._items)
+        if raw_lines < 500 or live > raw_lines * (1 - ratio):
+            return
+        tmp = self.path.with_suffix(".jsonl.tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            for mem in self._items.values():
+                fh.write(mem.to_json() + "\n")
+        os.replace(tmp, self.path)

meshctx_ctxkit/server.py

@@ -0,0 +1,241 @@
+"""ctxkit MCP server — stdio JSON-RPC, zero dependencies.
+
+Speaks the Model Context Protocol over stdio so Claude Desktop, Cursor,
+Cline, Windsurf, Zed and any MCP client can use it. Deliberately
+hand-rolled (no `mcp` SDK import) so ``pip install ctxkit`` pulls
+nothing: the whole point is a memory layer that works offline, in a
+clean venv, on a plane.
+
+Tools (free, fully offline):
+    ctx_remember(text, tags?)       -> store a memory locally
+    ctx_recall(query, limit?, tags?) -> BM25-style retrieval
+    ctx_forget(id)                   -> delete a memory
+    ctx_stats()                      -> store stats
+    ctx_verify_text(text)            -> offline sanity checks
+        (arithmetic / dates / absolutes / URLs)
+
+Tools (optional, paid path, needs httpx + CTXKIT_API_KEY):
+    ctx_consensus(question, models?) -> N-model cross-check report
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from . import __version__
+from .memory import MemoryStore
+from .consensus import run_offline_checks, multi_model_consensus
+from .license import License, load_license_from_env
+from .usage import UsageMeter
+
+PROTOCOL_VERSION = "2024-11-05"
+DEFAULT_MODELS = ["gpt-4o-mini", "claude-3-5-haiku", "gemini-2.0-flash"]
+
+
+class CtxKitServer:
+    def __init__(self, store: MemoryStore | None = None,
+                 license_: License | None = None,
+                 meter: UsageMeter | None = None) -> None:
+        self.store = store or MemoryStore()
+        self.license = license_ or load_license_from_env()
+        self.meter = meter or UsageMeter(self.store.path.parent)
+
+    # ── tool implementations ───────────────────────────────────────────
+    def tool_remember(self, args: dict[str, Any]) -> str:
+        mem = self.store.remember(
+            text=args.get("text", ""),
+            tags=args.get("tags") or [],
+            source=args.get("source", "mcp"),
+        )
+        return json.dumps({"ok": True, "id": mem.id,
+                           "note": "stored locally; survives restarts"},
+                          ensure_ascii=False)
+
+    def tool_recall(self, args: dict[str, Any]) -> str:
+        hits = self.store.recall(
+            query=args.get("query", ""),
+            limit=args.get("limit", 5),
+            tags=args.get("tags"),
+        )
+        return json.dumps({"ok": True, "hits": hits}, ensure_ascii=False)
+
+    def tool_forget(self, args: dict[str, Any]) -> str:
+        ok = self.store.forget(args.get("id", ""))
+        return json.dumps({"ok": ok, "id": args.get("id", "")})
+
+    def tool_stats(self, args: dict[str, Any]) -> str:  # noqa: ARG002
+        return json.dumps({"ok": True, **self.store.stats()}, ensure_ascii=False)
+
+    def tool_verify(self, args: dict[str, Any]) -> str:
+        text = args.get("text", "")
+        if not text:
+            return json.dumps({"ok": False, "error": "text required"})
+        return json.dumps({"ok": True, **run_offline_checks(text)},
+                          ensure_ascii=False)
+
+    def tool_consensus(self, args: dict[str, Any]) -> str:
+        question = args.get("question", "").strip()
+        if not question:
+            return json.dumps({"ok": False, "error": "question required"})
+        lic = self.license
+        if not lic.active:
+            return json.dumps({
+                "ok": False,
+                "error": "ctx_consensus requires a paid license",
+                "tier": lic.tier,
+                "detail": lic.reason,
+                "upgrade": "https://github.com/LucyAndLuna2023/meshctx#pricing",
+                "note": "ctx_remember / ctx_recall / ctx_verify_text stay free forever",
+            }, ensure_ascii=False)
+        allowed, used = self.meter.check_and_consume(lic.consensus_quota)
+        if not allowed:
+            return json.dumps({
+                "ok": False,
+                "error": f"monthly consensus quota reached "
+                         f"({used}/{lic.consensus_quota} on {lic.tier})",
+                "resets": "1st of next month (UTC)",
+            }, ensure_ascii=False)
+        models = args.get("models") or _env_models() or DEFAULT_MODELS
+        try:
+            report = multi_model_consensus(question, models,
+                                           timeout=float(args.get("timeout", 120)))
+        except Exception as e:
+            return json.dumps({"ok": False, "error": str(e)[:300]})
+        report["quota"] = {"used": used, "limit": lic.consensus_quota, "tier": lic.tier}
+        return json.dumps({"ok": True, **report}, ensure_ascii=False)
+
+    def tool_license(self, args: dict[str, Any]) -> str:  # noqa: ARG002
+        lic = self.license.to_dict()
+        lic["usage"] = self.meter.snapshot()
+        lic["free_tools"] = ["ctx_remember", "ctx_recall", "ctx_forget",
+                             "ctx_stats", "ctx_verify_text"]
+        return json.dumps({"ok": True, **lic}, ensure_ascii=False)
+
+    # ── MCP protocol surface ───────────────────────────────────────────
+    def tools_schema(self) -> list[dict[str, Any]]:
+        return [
+            {"name": "ctx_remember",
+             "description": ("Save a durable local memory (facts, decisions, "
+                             "preferences, project state). Survives restarts. "
+                             "Stored on this machine only."),
+             "inputSchema": {"type": "object", "properties": {
+                 "text": {"type": "string", "description": "the fact/memory to keep"},
+                 "tags": {"type": "array", "items": {"type": "string"}},
+                 "source": {"type": "string", "description": "who saved it"}},
+                 "required": ["text"]}},
+            {"name": "ctx_recall",
+             "description": ("Retrieve relevant memories by keyword query "
+                             "(BM25-style, offline, no embeddings needed)."),
+             "inputSchema": {"type": "object", "properties": {
+                 "query": {"type": "string"},
+                 "limit": {"type": "integer", "description": "default 5"},
+                 "tags": {"type": "array", "items": {"type": "string"}}},
+                 "required": ["query"]}},
+            {"name": "ctx_forget",
+             "description": "Delete a stored memory by id.",
+             "inputSchema": {"type": "object", "properties": {
+                 "id": {"type": "string"}}, "required": ["id"]}},
+            {"name": "ctx_stats",
+             "description": "Memory store statistics (count, tags, disk path).",
+             "inputSchema": {"type": "object", "properties": {}}},
+            {"name": "ctx_verify_text",
+             "description": ("Offline sanity checks on generated text: recompute "
+                             "stated arithmetic, validate dates, flag unqualified "
+                             "absolutes and suspicious URLs. Free, no network."),
+             "inputSchema": {"type": "object", "properties": {
+                 "text": {"type": "string"}}, "required": ["text"]}},
+            {"name": "ctx_consensus",
+             "description": ("Ask the same question to several models and score "
+                             "agreement of their key claims. Catches single-model "
+                             "hallucinations. Requires CTXKIT_API_KEY (paid tier)."),
+             "inputSchema": {"type": "object", "properties": {
+                 "question": {"type": "string"},
+                 "models": {"type": "array", "items": {"type": "string"},
+                            "description": "default: 3 hosted models"},
+                 "timeout": {"type": "number"}},
+                 "required": ["question"]}},
+            {"name": "ctx_license",
+             "description": ("Show current license tier, expiry, this month's "
+                             "consensus usage, and which tools are free."),
+             "inputSchema": {"type": "object", "properties": {}}},
+        ]
+
+    def call_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
+        handlers = {
+            "ctx_remember": self.tool_remember,
+            "ctx_recall": self.tool_recall,
+            "ctx_forget": self.tool_forget,
+            "ctx_stats": self.tool_stats,
+            "ctx_verify_text": self.tool_verify,
+            "ctx_consensus": self.tool_consensus,
+            "ctx_license": self.tool_license,
+        }
+        h = handlers.get(name)
+        if h is None:
+            return {"isError": True,
+                    "content": [{"type": "text", "text": f"unknown tool: {name}"}]}
+        try:
+            text = h(args or {})
+            return {"content": [{"type": "text", "text": text}]}
+        except Exception as e:
+            return {"isError": True,
+                    "content": [{"type": "text", "text": f"{type(e).__name__}: {e}"}]}
+
+    def handle(self, msg: dict[str, Any]) -> dict[str, Any] | None:
+        method = msg.get("method", "")
+        mid = msg.get("id")
+        params = msg.get("params") or {}
+        if method == "initialize":
+            return {"jsonrpc": "2.0", "id": mid, "result": {
+                "protocolVersion": params.get("protocolVersion") or PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "ctxkit", "version": __version__}}}
+        if method == "notifications/initialized":
+            return None  # notification: no response
+        if method == "ping":
+            return {"jsonrpc": "2.0", "id": mid, "result": {}}
+        if method == "tools/list":
+            return {"jsonrpc": "2.0", "id": mid, "result": {"tools": self.tools_schema()}}
+        if method == "tools/call":
+            name = params.get("name", "")
+            result = self.call_tool(name, params.get("arguments") or {})
+            return {"jsonrpc": "2.0", "id": mid, "result": result}
+        if mid is not None:
+            return {"jsonrpc": "2.0", "id": mid,
+                    "error": {"code": -32601, "message": f"method not found: {method}"}}
+        return None
+
+
+def _env_models() -> list[str] | None:
+    raw = os.environ.get("CTXKIT_MODELS", "").strip()
+    return [m.strip() for m in raw.split(",") if m.strip()] or None
+
+
+def main() -> None:
+    server = CtxKitServer()
+    out = sys.stdout.buffer
+    inp = sys.stdin.buffer
+    while True:
+        # readline() (not iteration): iterating stdin.buffer keeps an internal
+        # read-ahead buffer and can miss EOF, leaving the process hung after
+        # the MCP client closes the pipe.
+        line = inp.readline()
+        if not line:
+            break
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        resp = server.handle(msg)
+        if resp is not None:
+            out.write((json.dumps(resp, ensure_ascii=False) + "\n").encode())
+            out.flush()
+
+
+if __name__ == "__main__":
+    main()

meshctx_ctxkit/usage.py

@@ -0,0 +1,70 @@
+"""Local usage metering for the paid tier.
+
+Deliberately local-only: we count calls in a JSON file next to the memory
+store. No telemetry, no phone-home, no user identification beyond what the
+license token already contains.
+
+The honest caveat, stated plainly: a local counter can be deleted by the
+user. That is fine. The paid feature costs *us* money per call (model API
+spend), so quotas protect against runaway bills and casual abuse, not
+against a determined attacker. Licensing protects revenue; the counter
+protects the credit card.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+
+class UsageMeter:
+    def __init__(self, root: str | os.PathLike) -> None:
+        self.path = Path(root) / "usage.json"
+        self._lock = threading.RLock()
+
+    def _load(self) -> dict[str, int]:
+        try:
+            with self.path.open("r", encoding="utf-8") as fh:
+                data = json.load(fh)
+                return {k: int(v) for k, v in data.items() if isinstance(v, (int, float))}
+        except (OSError, json.JSONDecodeError, ValueError):
+            return {}
+
+    def _save(self, data: dict[str, int]) -> None:
+        tmp = self.path.with_suffix(".json.tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            json.dump(data, fh)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, self.path)
+
+    @staticmethod
+    def _month_key(now: float | None = None) -> str:
+        t = time.gmtime(now or time.time())
+        return f"consensus:{t.tm_year}-{t.tm_mon:02d}"
+
+    def used(self, now: float | None = None) -> int:
+        with self._lock:
+            return self._load().get(self._month_key(now), 0)
+
+    def check_and_consume(self, quota: int, now: float | None = None) -> tuple[bool, int]:
+        """Atomically reserve one call. Returns (allowed, used_after)."""
+        with self._lock:
+            data = self._load()
+            key = self._month_key(now)
+            used = data.get(key, 0)
+            if used >= quota:
+                return False, used
+            data[key] = used + 1
+            self._save(data)
+            return True, data[key]
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            data = self._load()
+        key = self._month_key()
+        return {"month": key.split(":", 1)[1], "used": data.get(key, 0),
+                "file": str(self.path)}