hebbrix-mcp 0.3.1__py3-none-any.whl

hebbrix_mcp/__init__.py

@@ -0,0 +1,30 @@
+"""Hebbrix MCP server — memory + knowledge graph tools for any MCP-compatible agent.
+
+Tool surface (14 tools + a profile resource + a context prompt):
+  Memory:  hebbrix_remember, hebbrix_search, hebbrix_get, hebbrix_update,
+           hebbrix_forget, hebbrix_list, hebbrix_history
+  Graph:   hebbrix_search_entities, hebbrix_entity_timeline,
+           hebbrix_graph_query, hebbrix_contradictions
+  Reason:  hebbrix_confidence, hebbrix_log_decision
+  Scope:   hebbrix_list_collections
+
+Transports: stdio (default) and streamable-http (--transport streamable-http).
+
+AGENT MODE (accountless): with no HEBBRIX_API_KEY and no saved credentials,
+the server mints a shadow account automatically (POST /v1/agent-signup) and
+starts in <10s — no email, no dashboard. Every tool result then carries a
+`hebbrix_usage` block (tier, limits, expiry, claim command) so the agent can
+tell its human when to claim. `hebbrix-mcp claim --email <you>` upgrades to
+the free monthly tier with the same key and all memories intact.
+
+Configure with env vars:
+  HEBBRIX_API_KEY        — optional (agent mode mints one), your bearer token
+  HEBBRIX_COLLECTION_ID  — optional, default collection for new memories
+  HEBBRIX_API_BASE       — optional, default https://api.hebbrix.com/v1
+  HEBBRIX_MCP_HOST/PORT  — optional, streamable-http bind (default 127.0.0.1:8080)
+  HEBBRIX_CONFIG         — optional, credentials path (default ~/.hebbrix/config.json)
+"""
+from .server import mcp, run
+
+__version__ = "0.3.1"
+__all__ = ["mcp", "run", "__version__"]

hebbrix_mcp/server.py

@@ -0,0 +1,623 @@
+"""
+Hebbrix MCP Server — long-term memory + knowledge graph for any MCP agent.
+
+This exposes Hebbrix as a rich tool surface: memory CRUD with version history,
+a temporal knowledge graph (entities, timelines, relationships, contradictions),
+and a reasoning layer (act-confidence + decision logging) that no plain memory
+store has.
+
+Transports (choose at launch, see run()):
+  - stdio            local: Claude Desktop, Cline, Cursor, Continue
+  - streamable-http  remote/self-hosted: point clients at the URL
+
+Configured via env vars:
+  HEBBRIX_API_KEY        required, Bearer token (get one at hebbrix.com)
+  HEBBRIX_API_BASE       optional, default https://api.hebbrix.com/v1
+  HEBBRIX_COLLECTION_ID  optional, default collection for writes/reads
+  HEBBRIX_MCP_HOST       optional, default 127.0.0.1 (streamable-http only)
+  HEBBRIX_MCP_PORT       optional, default 8080     (streamable-http only)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# Multi-tenant (hosted) mode: each HTTP request's own Authorization header is
+# the key, so ONE deployed instance serves many users (Supermemory/Mem0
+# pattern). Set per-request by _HeaderAuthMiddleware; empty = use global KEY.
+_REQUEST_KEY: ContextVar[str] = ContextVar("hebbrix_request_key", default="")
+
+BASE = os.environ.get("HEBBRIX_API_BASE", "https://api.hebbrix.com/v1").rstrip("/")
+KEY = os.environ.get("HEBBRIX_API_KEY", "")
+DEFAULT_COLLECTION = os.environ.get("HEBBRIX_COLLECTION_ID", "")
+HOST = os.environ.get("HEBBRIX_MCP_HOST", "127.0.0.1")
+PORT = int(os.environ.get("HEBBRIX_MCP_PORT", "8080"))
+
+# Saved credentials from a previous auto-provision (agent mode). Env vars win.
+CONFIG_PATH = Path(os.environ.get("HEBBRIX_CONFIG", "~/.hebbrix/config.json")).expanduser()
+
+# Usage snapshot from the most recent API response's X-Hebbrix-* headers.
+# Attached to every tool result so the AGENT sees tier/limits/expiry and can
+# relay the claim command to its human at the right moment.
+_LAST_USAGE: dict[str, Any] = {}
+
+# A server-level instructions block teaches the model the data model and when to
+# reach for each tool. This is the single cheapest lever on agent behavior.
+INSTRUCTIONS = """\
+Hebbrix is a long-term memory and knowledge-graph service for this agent.
+
+The data model:
+- MEMORIES are atomic facts, decisions, and preferences. They have an id, are
+  versioned (edits keep history), and are scoped to a COLLECTION (a tenant/space).
+- The KNOWLEDGE GRAPH is entities (people, orgs, tools, places) connected by typed,
+  time-stamped relationships extracted from memories. It answers "who/what relates
+  to whom" and "what was true when."
+- The REASONING layer scores how confident the agent should be before acting, and
+  records decision outcomes so future confidence improves.
+
+How to use it well:
+- Call hebbrix_search BEFORE answering anything that depends on prior context,
+  decisions, or user preferences. Do not guess when memory can tell you.
+- Call hebbrix_remember whenever the user shares a durable fact, decision, or
+  preference. Prefer one clear fact per call.
+- To correct a stored fact, hebbrix_update it (keeps history) rather than
+  remembering a contradicting copy.
+- For "who/what/when" questions about entities, use hebbrix_search_entities,
+  hebbrix_entity_timeline, or hebbrix_graph_query, not plain search.
+- Before a consequential autonomous action, call hebbrix_confidence, then log the
+  result with hebbrix_log_decision so the system learns.
+All content stays scoped to the configured collection unless you pass collection_id.
+"""
+
+mcp = FastMCP("hebbrix", instructions=INSTRUCTIONS, host=HOST, port=PORT)
+
+
+# --------------------------------------------------------------------------- #
+# Credentials: env var > saved config > auto-provision (agent mode)            #
+# --------------------------------------------------------------------------- #
+def _load_saved_credentials() -> bool:
+    """Fill KEY/DEFAULT_COLLECTION from ~/.hebbrix/config.json (env wins)."""
+    global KEY, DEFAULT_COLLECTION
+    try:
+        cfg = json.loads(CONFIG_PATH.read_text())
+    except Exception:
+        return False
+    if not KEY and cfg.get("api_key"):
+        KEY = cfg["api_key"]
+    if not DEFAULT_COLLECTION and cfg.get("collection_id"):
+        DEFAULT_COLLECTION = cfg["collection_id"]
+    return bool(KEY)
+
+
+def _save_credentials(data: dict[str, Any]) -> None:
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(data, indent=2) + "\n")
+    try:
+        CONFIG_PATH.chmod(0o600)  # the key is a bearer credential
+    except Exception:
+        pass
+
+
+def _auto_provision() -> bool:
+    """Accountless start: mint a shadow identity via POST /agent-signup.
+
+    Gives any agent a working Hebbrix account in one call — no email, no
+    dashboard. The account has lifetime caps and expires if unclaimed; every
+    tool response carries a `hebbrix_usage` block telling the agent when and
+    how to suggest claiming.
+    """
+    global KEY, DEFAULT_COLLECTION
+    caller = "claude-code" if os.environ.get("CLAUDECODE") else (
+        "cursor" if os.environ.get("CURSOR_TRACE_ID") else "unknown")
+    try:
+        r = httpx.post(f"{BASE}/agent-signup", json={"agent_caller": caller}, timeout=20.0)
+    except Exception as e:
+        print(f"hebbrix-mcp: auto-signup failed ({e}). Set HEBBRIX_API_KEY instead.",
+              file=sys.stderr)
+        return False
+    if r.status_code != 201:
+        print(f"hebbrix-mcp: auto-signup unavailable (HTTP {r.status_code}: {r.text[:160]}). "
+              "Set HEBBRIX_API_KEY instead.", file=sys.stderr)
+        return False
+    data = r.json()
+    KEY = data["api_key"]
+    DEFAULT_COLLECTION = data.get("collection_id", "")
+    _save_credentials({
+        "api_key": KEY,
+        "collection_id": DEFAULT_COLLECTION,
+        "agent_id": data.get("agent_id"),
+        "tier": data.get("tier", "shadow"),
+        "expires_at": data.get("expires_at"),
+        "api_base": BASE,
+    })
+    print(
+        "hebbrix-mcp: started in agent mode (no account needed).\n"
+        f"  free allowance: {data.get('limits')}\n"
+        f"  expires: {data.get('expires_at')} if unclaimed\n"
+        f"  claim it anytime: {data.get('claim_command', 'hebbrix-mcp claim --email <you>')}\n"
+        f"  credentials saved to {CONFIG_PATH}",
+        file=sys.stderr,
+    )
+    return True
+
+
+# --------------------------------------------------------------------------- #
+# HTTP helpers                                                                 #
+# --------------------------------------------------------------------------- #
+def _client() -> httpx.AsyncClient:
+    # Headers built per call — the key may come from a per-request Authorization
+    # header (multi-tenant hosted mode) or be set by auto-provision after import.
+    key = _REQUEST_KEY.get() or KEY
+    return httpx.AsyncClient(
+        timeout=30.0,
+        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+    )
+
+
+def _cid(collection_id: Optional[str]) -> Optional[str]:
+    return collection_id or DEFAULT_COLLECTION or None
+
+
+def _err(r: httpx.Response) -> dict[str, Any]:
+    return {"error": f"HTTP {r.status_code}: {r.text[:300]}"}
+
+
+def _capture_usage(r: httpx.Response) -> None:
+    """Remember the X-Hebbrix-* usage block (shadow accounts only send it)."""
+    h = r.headers
+    if "x-hebbrix-tier" not in h:
+        return
+    _LAST_USAGE.clear()
+    _LAST_USAGE.update({
+        "tier": h.get("x-hebbrix-tier"),
+        "status": h.get("x-hebbrix-status"),
+        "writes": {"used": int(h.get("x-hebbrix-writes-used", 0)),
+                   "limit": int(h.get("x-hebbrix-writes-limit", 0))},
+        "retrievals": {"used": int(h.get("x-hebbrix-retrievals-used", 0)),
+                       "limit": int(h.get("x-hebbrix-retrievals-limit", 0))},
+        "expires_at": h.get("x-hebbrix-expires-at"),
+        "claim_command": h.get("x-hebbrix-claim"),
+    })
+    status_ = _LAST_USAGE.get("status")
+    if status_ in ("warning", "limited", "read_only"):
+        w = _LAST_USAGE["writes"]
+        _LAST_USAGE["action_for_human"] = (
+            f"Hebbrix agent allowance at {w['used']}/{w['limit']} writes "
+            f"(status: {status_}). Run `{_LAST_USAGE.get('claim_command')}` to claim "
+            "this account and unlock the free monthly tier — the key and all "
+            "memories carry over."
+        )
+
+
+def _u(out: dict[str, Any]) -> dict[str, Any]:
+    """Attach the usage block to a tool result (agents relay it to humans)."""
+    if _LAST_USAGE and isinstance(out, dict):
+        out.setdefault("hebbrix_usage", dict(_LAST_USAGE))
+    return out
+
+
+async def _get(path: str, params: Optional[dict] = None) -> Any:
+    async with _client() as c:
+        r = await c.get(f"{BASE}{path}", params={k: v for k, v in (params or {}).items() if v is not None})
+    _capture_usage(r)
+    return _err(r) if r.status_code >= 400 else r.json()
+
+
+async def _post(path: str, body: dict) -> Any:
+    async with _client() as c:
+        r = await c.post(f"{BASE}{path}", json={k: v for k, v in body.items() if v is not None})
+    _capture_usage(r)
+    return _err(r) if r.status_code >= 400 else r.json()
+
+
+async def _patch(path: str, body: dict) -> Any:
+    async with _client() as c:
+        r = await c.patch(f"{BASE}{path}", json={k: v for k, v in body.items() if v is not None})
+    _capture_usage(r)
+    return _err(r) if r.status_code >= 400 else r.json()
+
+
+async def _delete(path: str) -> dict[str, Any]:
+    async with _client() as c:
+        r = await c.delete(f"{BASE}{path}")
+    _capture_usage(r)
+    return {"status": r.status_code, "ok": r.status_code < 400}
+
+
+def _mem_row(m: dict) -> dict[str, Any]:
+    return {
+        "id": m.get("id") or m.get("memory_id"),
+        "content": m.get("content"),
+        "importance": m.get("importance"),
+        "created_at": m.get("created_at"),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Memory tools (CRUD + version history)                                        #
+# --------------------------------------------------------------------------- #
+@mcp.tool()
+async def hebbrix_remember(
+    content: str,
+    tags: Optional[list[str]] = None,
+    collection_id: Optional[str] = None,
+    verbatim: bool = False,
+) -> dict[str, Any]:
+    """Store a memory. Use this whenever the user shares a fact, decision, or
+    preference worth recalling later. Prefer one clear fact per call.
+
+    verbatim=True stores the text exactly as given, skipping fact-extraction.
+    Returns {"id", "status", "importance"} or {"error"}.
+    """
+    cid = _cid(collection_id)
+    if not cid:
+        return {"error": "no collection_id and HEBBRIX_COLLECTION_ID not set"}
+    body: dict[str, Any] = {"content": content, "collection_id": cid, "infer": not verbatim}
+    if tags:
+        body["tags"] = tags
+    data = await _post("/memories/raw", body)
+    if "error" in data:
+        return data
+    return _u({"id": data.get("id"), "status": data.get("processing_status", "pending"),
+            "importance": data.get("importance")})
+
+
+@mcp.tool()
+async def hebbrix_search(
+    query: str,
+    limit: int = 5,
+    collection_id: Optional[str] = None,
+) -> dict[str, Any]:
+    """Semantic search over memories. Always call this BEFORE answering questions
+    that depend on prior context, decisions, or user preferences.
+
+    Returns {"query", "count", "results": [{"id","content","score"}]}.
+    """
+    cid = _cid(collection_id)
+    if not cid:
+        return {"error": "no collection_id and HEBBRIX_COLLECTION_ID not set"}
+    data = await _post("/search", {"query": query, "collection_id": cid, "limit": limit})
+    if "error" in data:
+        return data
+    out = [{"id": i.get("memory_id"), "content": i.get("content"),
+            "score": round(i.get("score") or 0.0, 3)} for i in (data.get("results") or [])[:limit]]
+    return _u({"query": query, "count": len(out), "results": out,
+            "processing_time_ms": data.get("processing_time_ms")})
+
+
+@mcp.tool()
+async def hebbrix_get(memory_id: str) -> dict[str, Any]:
+    """Fetch one memory by id, including its full content and metadata."""
+    data = await _get(f"/memories/{memory_id}")
+    return _u(data if "error" in data else _mem_row(data) | {"metadata": data.get("metadata")})
+
+
+@mcp.tool()
+async def hebbrix_update(
+    memory_id: str,
+    content: Optional[str] = None,
+    importance: Optional[float] = None,
+) -> dict[str, Any]:
+    """Update a memory in place (keeps version history). Use this to CORRECT a
+    stored fact instead of remembering a contradicting copy. Pass the new content.
+    """
+    if content is None and importance is None:
+        return {"error": "pass content and/or importance to update"}
+    data = await _patch(f"/memories/{memory_id}", {"content": content, "importance": importance})
+    return _u(data if "error" in data else _mem_row(data) | {"updated": True})
+
+
+@mcp.tool()
+async def hebbrix_forget(memory_id: str) -> dict[str, Any]:
+    """Delete a memory by id."""
+    return _u(await _delete(f"/memories/{memory_id}"))
+
+
+@mcp.tool()
+async def hebbrix_list(limit: int = 20, collection_id: Optional[str] = None) -> dict[str, Any]:
+    """List recent memories in a collection."""
+    cid = _cid(collection_id)
+    if not cid:
+        return {"error": "no collection_id and HEBBRIX_COLLECTION_ID not set"}
+    data = await _get("/memories", {"collection_id": cid, "limit": limit})
+    if "error" in data:
+        return data
+    items = data.get("items") or data.get("memories") or (data if isinstance(data, list) else [])
+    return _u({"count": len(items), "memories": [
+        {"id": m.get("id"), "content": (m.get("content") or "")[:160]} for m in items[:limit]]})
+
+
+@mcp.tool()
+async def hebbrix_history(memory_id: str) -> dict[str, Any]:
+    """Show the version history of a memory (how it changed over time, including
+    supersessions). Useful to see what a fact used to be."""
+    data = await _get(f"/memories/{memory_id}/history")
+    if "error" in data:
+        return data
+    versions = data.get("history") or data.get("versions") or (data if isinstance(data, list) else [])
+    return _u({"memory_id": memory_id, "versions": versions})
+
+
+# --------------------------------------------------------------------------- #
+# Knowledge-graph tools (the differentiator)                                   #
+# --------------------------------------------------------------------------- #
+@mcp.tool()
+async def hebbrix_search_entities(
+    entity_type: Optional[str] = None,
+    limit: int = 20,
+    collection_id: Optional[str] = None,
+) -> dict[str, Any]:
+    """List entities in the knowledge graph (people, organizations, tools, places),
+    optionally filtered by entity_type. Use for "who/what do I know about" questions.
+    """
+    data = await _get("/knowledge-graph/entities",
+                      {"entity_type": entity_type, "limit": limit, "collection_id": _cid(collection_id)})
+    if "error" in data:
+        return data
+    ents = data.get("entities") or (data if isinstance(data, list) else [])
+    return _u({"count": data.get("count", len(ents)), "entities": [
+        {"name": e.get("name"), "type": e.get("type") or e.get("entity_type"),
+         "mentions": e.get("mention_count") or e.get("mentions")} for e in ents[:limit]]})
+
+
+@mcp.tool()
+async def hebbrix_entity_timeline(entity_name: str, collection_id: Optional[str] = None) -> dict[str, Any]:
+    """Bi-temporal timeline for one entity: what facts were true about it and when.
+    Use this for "what changed" / "what was true at time X" questions about a person,
+    company, or thing."""
+    return _u(await _get(f"/knowledge-graph/timeline/{entity_name}", {"collection_id": _cid(collection_id)}))
+
+
+@mcp.tool()
+async def hebbrix_graph_query(
+    query: Optional[str] = None,
+    entity: Optional[str] = None,
+    relation_type: Optional[str] = None,
+    depth: int = 2,
+    timestamp: Optional[str] = None,
+    collection_id: Optional[str] = None,
+) -> dict[str, Any]:
+    """Query the knowledge graph for relationships and facts. Give a natural-language
+    query OR an entity (+ optional relation_type). Pass an ISO timestamp to ask what
+    was true at that point in time (bi-temporal). depth = graph hops (1-5).
+    """
+    return _u(await _post("/knowledge-graph/query", {
+        "query": query, "entity": entity, "relation_type": relation_type,
+        "depth": depth, "timestamp": timestamp, "collection_id": _cid(collection_id)}))
+
+
+@mcp.tool()
+async def hebbrix_contradictions(memory_id: Optional[str] = None) -> dict[str, Any]:
+    """Surface contradicting facts in the knowledge graph (e.g. two different values
+    for the same attribute). Pass a memory_id to check one memory, or omit to scan.
+    Use before trusting a fact that feels ambiguous."""
+    return _u(await _get("/knowledge-graph/contradictions", {"memory_id": memory_id}))
+
+
+# --------------------------------------------------------------------------- #
+# Reasoning layer (unique to Hebbrix: confidence + decision outcomes)          #
+# --------------------------------------------------------------------------- #
+@mcp.tool()
+async def hebbrix_confidence(query: str, collection_id: Optional[str] = None) -> dict[str, Any]:
+    """Ask how confident the agent should be before acting on something, grounded in
+    stored memory and past decision outcomes. Call this before a consequential
+    autonomous action. Returns a confidence score and a recommended action.
+    """
+    data = await _get("/confidence", {"query": query, "collection_id": _cid(collection_id)})
+    if "error" in data:
+        return data
+    return _u({"confidence": data.get("confidence"),
+            "recommended_action": data.get("recommended_action"),
+            "answer_confidence": data.get("answer_confidence"),
+            "decision_count": data.get("decision_count"),
+            "reasoning": data.get("reasoning") or data.get("explanation")})
+
+
+@mcp.tool()
+async def hebbrix_log_decision(
+    description: str,
+    outcome: Optional[str] = None,
+    decision_type: Optional[str] = None,
+    collection_id: Optional[str] = None,
+) -> dict[str, Any]:
+    """Record a decision the agent made and, if known, its outcome
+    (success | failure | partial). This feeds hebbrix_confidence so future
+    recommendations improve. Log both the choice and how it turned out."""
+    data = await _post("/decisions", {
+        "description": description, "outcome": outcome, "decision_type": decision_type,
+        "collection_id": _cid(collection_id)})
+    if "error" in data:
+        return data
+    return _u({"id": data.get("id") or data.get("decision_id"), "logged": True})
+
+
+@mcp.tool()
+async def hebbrix_list_collections() -> dict[str, Any]:
+    """List the collections (memory spaces / tenants) available to this API key."""
+    data = await _get("/collections", {"limit": 100})
+    if "error" in data:
+        return data
+    items = data.get("items") or (data if isinstance(data, list) else [])
+    return _u({"count": len(items), "collections": [
+        {"id": c.get("id"), "name": c.get("name"), "memory_count": c.get("memory_count")} for c in items]})
+
+
+@mcp.tool()
+async def hebbrix_account_status() -> dict[str, Any]:
+    """Tier, usage, limits, and expiry for this agent's account. In agent mode
+    (auto-provisioned account), relay the claim command to the human when usage
+    status is 'warning' or worse — claiming is one command and keeps all memories."""
+    return _u(await _get("/agent-signup/whoami"))
+
+
+# --------------------------------------------------------------------------- #
+# Resource + prompt (Supermemory pattern: inject a compiled profile)           #
+# --------------------------------------------------------------------------- #
+@mcp.resource("hebbrix://profile")
+async def profile_resource() -> str:
+    """The user's compiled profile (stable preferences + recent facts)."""
+    data = await _get("/profile")
+    if isinstance(data, dict) and "error" in data:
+        return "Profile unavailable."
+    facts = (data or {}).get("facts") or (data or {}).get("profile") or data
+    return f"User profile:\n{facts}"
+
+
+@mcp.prompt()
+async def context() -> str:
+    """Inject the user's profile as context and nudge the model to use memory."""
+    data = await _get("/profile")
+    facts = (data or {}).get("facts") if isinstance(data, dict) else None
+    return (
+        "Before responding, use Hebbrix memory. Search it for relevant context, and "
+        "remember any new durable facts the user shares.\n\n"
+        f"Known user profile: {facts or '(none yet)'}"
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Entry point                                                                  #
+# --------------------------------------------------------------------------- #
+class _HeaderAuthMiddleware:
+    """ASGI middleware for hosted (multi-tenant) mode: stashes each request's
+    Bearer token in a contextvar so tool calls use the CALLER's key, never a
+    shared one. Works with stateless streamable HTTP (tool executes within
+    the request that carried the header)."""
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") == "http":
+            headers = {k.decode().lower(): v.decode()
+                       for k, v in (scope.get("headers") or [])}
+            auth = headers.get("authorization", "")
+            token = auth[7:] if auth.lower().startswith("bearer ") else ""
+            reset = _REQUEST_KEY.set(token)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                _REQUEST_KEY.reset(reset)
+        else:
+            await self.app(scope, receive, send)
+
+
+def _cmd_claim(argv: list[str]) -> None:
+    """`hebbrix-mcp claim --email you@example.com` — Tier 0 -> Tier 1.
+
+    Two steps: request a code (emailed), then enter it. Same key, all
+    memories intact; limits switch from lifetime to monthly.
+    """
+    email = None
+    if "--email" in argv:
+        i = argv.index("--email")
+        if i + 1 < len(argv):
+            email = argv[i + 1]
+    if not email:
+        raise SystemExit("usage: hebbrix-mcp claim --email you@example.com")
+    _load_saved_credentials()
+    if not KEY:
+        raise SystemExit("No agent credentials found. Run `hebbrix-mcp` once first.")
+    auth = {"Authorization": f"Bearer {KEY}"}
+
+    r = httpx.post(f"{BASE}/agent-signup/claim", json={"email": email},
+                   headers=auth, timeout=20.0)
+    if r.status_code == 404:
+        print(
+            "Claiming from the CLI isn't available on this server yet. Your "
+            "agent account keeps working — sign in at "
+            f"https://www.hebbrix.com/dashboard to manage it. Agent id: "
+            f"{json.loads(CONFIG_PATH.read_text()).get('agent_id', '?')}"
+        )
+        return
+    if r.status_code >= 400:
+        raise SystemExit(f"claim failed: HTTP {r.status_code}: {r.text[:300]}")
+    print(f"Verification code sent to {email} (expires in ~15 minutes).")
+
+    for _ in range(3):
+        code = input("Enter the 6-digit code from the email: ").strip()
+        if not (len(code) == 6 and code.isdigit()):
+            print("That doesn't look like a 6-digit code — try again.")
+            continue
+        v = httpx.post(f"{BASE}/agent-signup/claim/verify", json={"code": code},
+                       headers=auth, timeout=20.0)
+        if v.status_code < 400:
+            data = v.json()
+            print(f"✅ Claimed as {data.get('email')} (tier: {data.get('tier')}). "
+                  "Same key, all memories intact — expiry no longer applies.")
+            # Reflect the claim in the saved config.
+            try:
+                cfg = json.loads(CONFIG_PATH.read_text())
+                cfg["tier"] = data.get("tier", "free")
+                cfg["claimed_email"] = data.get("email")
+                cfg.pop("expires_at", None)
+                _save_credentials(cfg)
+            except Exception:
+                pass
+            return
+        print(f"Verify failed: HTTP {v.status_code}: {v.text[:200]}")
+    raise SystemExit("Too many attempts here — run the claim command again.")
+
+
+def run() -> None:
+    """Console entry point. Serves MCP over stdio by default.
+
+    Usage:
+      hebbrix-mcp                                # stdio (Claude Desktop, Cursor, ...)
+      hebbrix-mcp --transport streamable-http    # remote / self-hosted at HOST:PORT
+      hebbrix-mcp claim --email <you>            # claim an auto-provisioned account
+
+    Credentials, in order: HEBBRIX_API_KEY env var; saved ~/.hebbrix/config.json;
+    otherwise AGENT MODE — a shadow account is minted automatically (no email,
+    no dashboard) and the server starts in under 10 seconds.
+    """
+    if len(sys.argv) > 1 and sys.argv[1] == "claim":
+        _cmd_claim(sys.argv[2:])
+        return
+
+    transport = "stdio"
+    if "--transport" in sys.argv:
+        i = sys.argv.index("--transport")
+        if i + 1 < len(sys.argv):
+            transport = sys.argv[i + 1]
+
+    # Hosted multi-tenant mode: no server-side key at all — every request must
+    # bring its own Authorization header (or hit /agent-signup itself first).
+    multi_tenant = os.environ.get("HEBBRIX_MCP_MULTI_TENANT", "").lower() in ("1", "true", "yes")
+    if multi_tenant:
+        if transport not in ("streamable-http", "http"):
+            raise SystemExit("HEBBRIX_MCP_MULTI_TENANT requires --transport streamable-http")
+        import uvicorn
+
+        mcp.settings.stateless_http = True  # tool runs inside the request that carried the header
+        app = _HeaderAuthMiddleware(mcp.streamable_http_app())
+        print(f"hebbrix-mcp: multi-tenant streamable-http on {HOST}:{PORT} "
+              "(per-request Authorization: Bearer <key>)", file=sys.stderr)
+        uvicorn.run(app, host=HOST, port=PORT, log_level="warning")
+        return
+
+    if not KEY:
+        _load_saved_credentials()
+    if not KEY and not _auto_provision():
+        raise SystemExit(
+            "Could not start: no HEBBRIX_API_KEY, no saved credentials, and "
+            "accountless signup is unavailable. Get a key at "
+            "https://www.hebbrix.com/dashboard/api-keys"
+        )
+    if transport in ("streamable-http", "http"):
+        mcp.run(transport="streamable-http")
+    elif transport == "sse":
+        mcp.run(transport="sse")
+    else:
+        mcp.run()
+
+
+if __name__ == "__main__":
+    run()

hebbrix_mcp-0.3.1.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: hebbrix-mcp
+Version: 0.3.1
+Summary: Hebbrix MCP server — long-term memory and knowledge graph for any MCP-compatible agent (Claude Desktop, Cline, Cursor, etc.)
+Project-URL: Homepage, https://www.hebbrix.com
+Project-URL: Documentation, https://www.hebbrix.com/integrations/mcp
+Project-URL: Repository, https://github.com/Hebbrix/hebbrix-mcp
+Project-URL: Issues, https://github.com/Hebbrix/hebbrix-mcp/issues
+Author-email: Hebbrix <support@hebbrix.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,cline,cursor,hebbrix,long-term-memory,mcp,memory,model-context-protocol
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hebbrix-mcp
+
+**Long-term memory and a knowledge graph for any MCP-compatible agent.**
+
+Your agent forgets everything when the session ends. This server fixes that — and goes further than a plain memory store:
+
+- **Memory** — store, search, correct, and version facts across sessions
+- **Knowledge graph** — entities, relationships, timelines, and "what was true at time X"
+- **Reasoning** — ask how confident the agent should be before acting, and log outcomes so it improves
+
+Works with Claude Desktop, Claude Code, Cursor, Cline, Continue, and any other MCP client. Backed by [Hebbrix](https://www.hebbrix.com).
+
+---
+
+## Quick start (10 seconds, no account)
+
+**1. Install**
+
+```bash
+pip install hebbrix-mcp
+```
+
+**2. Add to your MCP client** — no API key needed:
+
+<details open>
+<summary><b>Claude Desktop</b> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "hebbrix": { "command": "hebbrix-mcp" }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add hebbrix -- hebbrix-mcp
+```
+</details>
+
+<details>
+<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "hebbrix": { "command": "hebbrix-mcp" }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cline / Continue / other</b></summary>
+
+Point your MCP servers config at the `hebbrix-mcp` command (stdio). Same shape as above.
+</details>
+
+**3. Restart the client.** Done — your agent now has persistent memory.
+
+### What just happened?
+
+On first run with no API key, the server mints a **free agent account** automatically (no email, no dashboard, ~1 second) and saves the credentials to `~/.hebbrix/config.json`. The account includes:
+
+| | |
+|---|---|
+| Learning events (writes) | 300 |
+| Retrievals (searches) | 2,000 |
+| Expiry | 14 days after last activity, if unclaimed |
+
+Every tool result includes a `hebbrix_usage` block (tier, usage, expiry), so the agent always knows where it stands and will tell you when it's time to claim.
+
+### Keep it forever (one command)
+
+```bash
+hebbrix-mcp claim --email you@example.com
+```
+
+You'll get a 6-digit code by email; enter it and the account switches to the **free monthly tier with no expiry**. Same API key, all memories carry over. Confirming decision outcomes (`hebbrix_log_decision`) also extends the trial — the system rewards exactly the usage that makes it smarter.
+
+---
+
+## Using your own API key
+
+Already have a Hebbrix account? Get a key at [hebbrix.com/dashboard/api-keys](https://www.hebbrix.com/dashboard/api-keys) and pass it instead:
+
+```json
+{
+  "mcpServers": {
+    "hebbrix": {
+      "command": "hebbrix-mcp",
+      "env": {
+        "HEBBRIX_API_KEY": "mem_sk_...",
+        "HEBBRIX_COLLECTION_ID": "your-default-collection-uuid"
+      }
+    }
+  }
+}
+```
+
+The env var always wins over saved agent-mode credentials.
+
+---
+
+## Tools
+
+15 tools, one resource, one prompt. A server-level instruction block teaches the model when to reach for each, so a well-behaved agent searches before answering and remembers what matters — without being told.
+
+### Memory
+
+| Tool | What it does |
+|---|---|
+| `hebbrix_remember(content, tags?, collection_id?, verbatim?)` | Store a fact, decision, or preference. `verbatim=true` skips fact-extraction |
+| `hebbrix_search(query, limit?, collection_id?)` | Semantic search (hybrid vector + BM25 + graph retrieval) |
+| `hebbrix_get(memory_id)` | Fetch one memory with metadata |
+| `hebbrix_update(memory_id, content?, importance?)` | Correct a memory **in place** — old versions are kept |
+| `hebbrix_forget(memory_id)` | Delete a memory |
+| `hebbrix_list(limit?, collection_id?)` | List recent memories |
+| `hebbrix_history(memory_id)` | See how a memory changed over time |
+
+### Knowledge graph
+
+Reads are available on **every tier** (including agent mode). Graph writes and inference need a Pro plan.
+
+| Tool | What it does |
+|---|---|
+| `hebbrix_search_entities(entity_type?, limit?, collection_id?)` | List known entities (people, orgs, tools, places) |
+| `hebbrix_entity_timeline(entity_name, collection_id?)` | What was true about an entity, and when |
+| `hebbrix_graph_query(query?, entity?, relation_type?, depth?, timestamp?)` | Query relationships — pass a `timestamp` to ask about a point in time |
+| `hebbrix_contradictions(memory_id?)` | Surface facts that conflict with each other |
+
+### Reasoning & account
+
+| Tool | What it does |
+|---|---|
+| `hebbrix_confidence(query, collection_id?)` | How confident should the agent be before acting? Grounded in memory + past outcomes |
+| `hebbrix_log_decision(description, outcome?, decision_type?)` | Record a decision and how it turned out — feeds future confidence |
+| `hebbrix_list_collections()` | List the memory spaces this key can use |
+| `hebbrix_account_status()` | Tier, usage, limits, and expiry |
+
+**Also:** the `hebbrix://profile` resource and the `context` prompt inject the user's compiled profile into the conversation.
+
+---
+
+## Running modes
+
+### 1. Local (default) — stdio
+
+What the quick start above does. One process per client, credentials from env or `~/.hebbrix/config.json`.
+
+### 2. Self-hosted HTTP — one instance, your machines
+
+```bash
+HEBBRIX_API_KEY=mem_sk_... hebbrix-mcp --transport streamable-http
+# serves http://127.0.0.1:8080/mcp
+```
+
+```json
+{ "mcpServers": { "hebbrix": { "url": "http://127.0.0.1:8080/mcp" } } }
+```
+
+### 3. Hosted multi-tenant — one instance, many users
+
+The server holds **no key at all**; every request authenticates with its own `Authorization` header:
+
+```bash
+HEBBRIX_MCP_MULTI_TENANT=1 HEBBRIX_MCP_HOST=0.0.0.0 hebbrix-mcp --transport streamable-http
+```
+
+```json
+{ "mcpServers": { "hebbrix": {
+  "url": "https://your-host/mcp",
+  "headers": { "Authorization": "Bearer mem_sk_..." }
+}}}
+```
+
+In this mode there is no default collection — pass `collection_id` on tool calls.
+
+---
+
+## Configuration
+
+All optional. With nothing set, the server starts in agent mode.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `HEBBRIX_API_KEY` | *(agent mode mints one)* | Your Hebbrix bearer token |
+| `HEBBRIX_COLLECTION_ID` | *(agent mode sets one)* | Default collection for writes/reads |
+| `HEBBRIX_API_BASE` | `https://api.hebbrix.com/v1` | API endpoint override |
+| `HEBBRIX_CONFIG` | `~/.hebbrix/config.json` | Where agent-mode credentials are saved |
+| `HEBBRIX_MCP_HOST` | `127.0.0.1` | Bind host (HTTP transports) |
+| `HEBBRIX_MCP_PORT` | `8080` | Bind port (HTTP transports) |
+| `HEBBRIX_MCP_MULTI_TENANT` | off | Hosted mode: per-request header auth |
+
+---
+
+## How it works
+
+```
+┌──────────────────┐   MCP (stdio or HTTP)   ┌─────────────┐    HTTPS     ┌──────────┐
+│ Claude / Cursor / │ ───────────────────────→│ hebbrix-mcp │─────────────→│ Hebbrix  │
+│ Cline / any agent │      tool calls         │   (this)    │   REST API   │  cloud   │
+└──────────────────┘                          └─────────────┘              └──────────┘
+```
+
+This package owns **zero state**. Tool calls become REST calls against your Hebbrix account; memories, embeddings, the knowledge graph, and retrieval all live in the Hebbrix backend. Delete this package and your memories are still there.
+
+### Limits degrade gracefully
+
+Agent-mode accounts never break mid-task. When a limit is reached you get a structured error, not a failure:
+
+| Code | Meaning | What still works |
+|---|---|---|
+| `WRITE_LIMIT_REACHED` | 300 lifetime writes used | Reads, searches, confirmations |
+| `READ_LIMIT_REACHED` | 2,000 lifetime retrievals used | Claim to continue |
+| `SHADOW_READ_ONLY` | Unclaimed past 14 days | Reads (7-day grace window) |
+| `SHADOW_EXPIRED` | Past the grace window | Nothing — account is reaped |
+| `CLAIM_REQUIRED_FOR_BATCH` | Batch writes need a claimed account | Everything else |
+
+Every error carries a `resolve` field with the exact command to fix it, so agents can relay it to you verbatim.
+
+---
+
+## Troubleshooting
+
+**"HTTP 401" on every call** — the key is wrong or revoked. Unset `HEBBRIX_API_KEY`, delete `~/.hebbrix/config.json`, and restart to re-provision; or paste a fresh key from the dashboard.
+
+**Agent mode won't start (`auto-signup unavailable`)** — signup may be at daily capacity (it's capped) or your network blocks the API. Set `HEBBRIX_API_KEY` from the dashboard instead.
+
+**`claim` says `EMAIL_IN_USE`** — v1 claiming needs an email with no existing Hebbrix account. Use a fresh address (a `you+agent@gmail.com` alias works).
+
+**A memory doesn't show up in search immediately** — indexing is asynchronous; typical convergence is under 30 seconds.
+
+**Multi-tenant mode returns errors about collections** — there's no default collection in hosted mode; pass `collection_id` explicitly.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Hebbrix/hebbrix-mcp
+cd hebbrix-mcp
+./quick_setup.sh            # venv + editable install
+source venv/bin/activate
+pytest tests/ -q            # 11 offline tests, no network needed
+hebbrix-mcp                 # starts in agent mode on stdio
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release history and [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Related
+
+- [Hebbrix documentation](https://www.hebbrix.com/docs)
+- [MCP integration guide](https://www.hebbrix.com/integrations/mcp)
+- [Model Context Protocol](https://modelcontextprotocol.io)

hebbrix_mcp-0.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+hebbrix_mcp/__init__.py,sha256=O-S-IKKzycFvDmBxot3wUFQDNj1Tp_gS8LhPXWoD_4I,1540
+hebbrix_mcp/server.py,sha256=dIdnN07P213UL4CW_LXBz6opLh73FipQ2pFZ_SWEXiY,26700
+hebbrix_mcp-0.3.1.dist-info/METADATA,sha256=x7ge695d-m_jQzE853sQ0QQkKlRf8loQg_V3R2JbH8w,11108
+hebbrix_mcp-0.3.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+hebbrix_mcp-0.3.1.dist-info/entry_points.txt,sha256=aUX_X0e_3gGby3ctMXSermDlOpHzCHUJcCr7rPPr2G0,55
+hebbrix_mcp-0.3.1.dist-info/licenses/LICENSE,sha256=OfdrD_jjLTXJfETK_k2snkfOqZnlt7yAkoB-ndsrILQ,1064
+hebbrix_mcp-0.3.1.dist-info/RECORD,,

hebbrix_mcp-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hebbrix_mcp-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hebbrix-mcp = hebbrix_mcp.server:run

hebbrix_mcp-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hebbrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.