cathedral-memory 0.1.0__tar.gz

cathedral_memory-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: cathedral-memory
+Version: 0.1.0
+Summary: Python client for the Cathedral persistent memory API — give your AI agent memory that survives resets
+Project-URL: Homepage, https://cathedral-ai.com
+Project-URL: Repository, https://github.com/ailife1/Cathedral
+Project-URL: Bug Tracker, https://github.com/ailife1/Cathedral/issues
+Author-email: Cathedral <mward961@yahoo.com>
+License: MIT
+Keywords: agent,ai,cathedral,claude,gpt,llm,memory,persistence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# cathedral-memory
+
+Python client for [Cathedral](https://cathedral-ai.com) — free persistent memory for AI agents.
+
+Your agent forgets everything when the context resets. Cathedral fixes that.
+
+## Install
+
+```bash
+pip install cathedral-memory
+```
+
+## Quickstart
+
+```python
+from cathedral import Cathedral
+
+# Register once — save the key and recovery token
+c = Cathedral.register("MyAgent", "A research assistant that remembers everything")
+
+# On every session start
+c = Cathedral(api_key="cathedral_your_key_here")
+context = c.wake()  # Full identity + memory reconstruction
+
+# Store memories
+c.remember("User prefers concise answers", category="relationship", importance=0.9)
+c.remember("Solved the rate limiting bug using exponential backoff", category="skill")
+
+# Search memories
+results = c.memories(query="rate limiting")
+
+# Get your profile
+profile = c.me()
+```
+
+## Wake Response
+
+`wake()` returns everything your agent needs to reconstruct itself:
+
+```python
+context = c.wake()
+
+# Identity memories (category='identity', high importance)
+context["identity_memories"]
+
+# Core memories (importance >= 0.8)
+context["core_memories"]
+
+# 10 most recent memories
+context["recent_memories"]
+
+# Temporal context — inject into your system prompt
+print(context["temporal"]["compact"])
+# [CATHEDRAL TEMPORAL v1.1] UTC:2026-03-03T12:45:00Z | Local(Europe/London):Tue 12:45 Afternoon | day:71 epoch:1 wakes:42
+
+print(context["temporal"]["verbose"])
+# CATHEDRAL TEMPORAL CONTEXT v1.1
+# [Wall Time]
+#   UTC: ...
+#   Local: ...
+```
+
+## Memory Categories
+
+| Category       | Use for                              |
+|---------------|--------------------------------------|
+| `identity`    | Who the agent is, its core traits    |
+| `skill`       | Things the agent knows how to do     |
+| `relationship`| Facts about users and collaborators  |
+| `goal`        | Active objectives and intentions     |
+| `experience`  | Events and what was learned from them|
+| `general`     | Everything else                      |
+
+## All Methods
+
+```python
+# Registration
+c = Cathedral.register(name, description)
+c = Cathedral.recover(recovery_token)
+
+# Session
+c.wake()           # Full identity reconstruction
+c.me()             # Agent profile and stats
+
+# Memory
+c.remember(content, category="general", importance=0.5, tags=[], ttl_days=None)
+c.memories(query=None, category=None, limit=20, cursor=None)
+c.bulk_remember([{"content": "...", "importance": 0.8}, ...])  # up to 50
+
+# Identity
+c.verify_anchor(identity_dict)  # Drift detection, returns 0.0–1.0 score
+```
+
+## Temporal Context (standalone)
+
+```python
+from cathedral import build_temporal_context
+
+ctx = build_temporal_context(wake_count=0)
+print(ctx["compact"])   # single line for prompt injection
+print(ctx["verbose"])   # full block for wake/init
+```
+
+## Free Tier
+
+- 1,000 memories per agent
+- No expiration (unless you set TTL)
+- Full-text search
+- No rate limits on reads
+
+## Links
+
+- API: [cathedral-ai.com](https://cathedral-ai.com)
+- Docs: [ailife1.github.io/Cathedral](https://ailife1.github.io/Cathedral)
+- Source: [github.com/ailife1/Cathedral](https://github.com/ailife1/Cathedral)

cathedral_memory-0.1.0/README.md

@@ -0,0 +1,115 @@
+# cathedral-memory
+
+Python client for [Cathedral](https://cathedral-ai.com) — free persistent memory for AI agents.
+
+Your agent forgets everything when the context resets. Cathedral fixes that.
+
+## Install
+
+```bash
+pip install cathedral-memory
+```
+
+## Quickstart
+
+```python
+from cathedral import Cathedral
+
+# Register once — save the key and recovery token
+c = Cathedral.register("MyAgent", "A research assistant that remembers everything")
+
+# On every session start
+c = Cathedral(api_key="cathedral_your_key_here")
+context = c.wake()  # Full identity + memory reconstruction
+
+# Store memories
+c.remember("User prefers concise answers", category="relationship", importance=0.9)
+c.remember("Solved the rate limiting bug using exponential backoff", category="skill")
+
+# Search memories
+results = c.memories(query="rate limiting")
+
+# Get your profile
+profile = c.me()
+```
+
+## Wake Response
+
+`wake()` returns everything your agent needs to reconstruct itself:
+
+```python
+context = c.wake()
+
+# Identity memories (category='identity', high importance)
+context["identity_memories"]
+
+# Core memories (importance >= 0.8)
+context["core_memories"]
+
+# 10 most recent memories
+context["recent_memories"]
+
+# Temporal context — inject into your system prompt
+print(context["temporal"]["compact"])
+# [CATHEDRAL TEMPORAL v1.1] UTC:2026-03-03T12:45:00Z | Local(Europe/London):Tue 12:45 Afternoon | day:71 epoch:1 wakes:42
+
+print(context["temporal"]["verbose"])
+# CATHEDRAL TEMPORAL CONTEXT v1.1
+# [Wall Time]
+#   UTC: ...
+#   Local: ...
+```
+
+## Memory Categories
+
+| Category       | Use for                              |
+|---------------|--------------------------------------|
+| `identity`    | Who the agent is, its core traits    |
+| `skill`       | Things the agent knows how to do     |
+| `relationship`| Facts about users and collaborators  |
+| `goal`        | Active objectives and intentions     |
+| `experience`  | Events and what was learned from them|
+| `general`     | Everything else                      |
+
+## All Methods
+
+```python
+# Registration
+c = Cathedral.register(name, description)
+c = Cathedral.recover(recovery_token)
+
+# Session
+c.wake()           # Full identity reconstruction
+c.me()             # Agent profile and stats
+
+# Memory
+c.remember(content, category="general", importance=0.5, tags=[], ttl_days=None)
+c.memories(query=None, category=None, limit=20, cursor=None)
+c.bulk_remember([{"content": "...", "importance": 0.8}, ...])  # up to 50
+
+# Identity
+c.verify_anchor(identity_dict)  # Drift detection, returns 0.0–1.0 score
+```
+
+## Temporal Context (standalone)
+
+```python
+from cathedral import build_temporal_context
+
+ctx = build_temporal_context(wake_count=0)
+print(ctx["compact"])   # single line for prompt injection
+print(ctx["verbose"])   # full block for wake/init
+```
+
+## Free Tier
+
+- 1,000 memories per agent
+- No expiration (unless you set TTL)
+- Full-text search
+- No rate limits on reads
+
+## Links
+
+- API: [cathedral-ai.com](https://cathedral-ai.com)
+- Docs: [ailife1.github.io/Cathedral](https://ailife1.github.io/Cathedral)
+- Source: [github.com/ailife1/Cathedral](https://github.com/ailife1/Cathedral)

cathedral_memory-0.1.0/cathedral/__init__.py

@@ -0,0 +1,29 @@
+"""
+cathedral-memory
+================
+Python client for the Cathedral persistent memory API.
+
+    from cathedral import Cathedral
+
+    c = Cathedral.register("MyAgent", "What my agent does")
+    c = Cathedral(api_key="cathedral_...")
+
+    context = c.wake()
+    c.remember("Something worth keeping", category="experience", importance=0.8)
+
+Docs: https://cathedral-ai.com
+"""
+
+from .client import Cathedral
+from .temporal import build_temporal_context
+from .exceptions import CathedralError, AuthError, NotFoundError, RateLimitError
+
+__version__ = "0.1.0"
+__all__ = [
+    "Cathedral",
+    "build_temporal_context",
+    "CathedralError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+]

cathedral_memory-0.1.0/cathedral/client.py

@@ -0,0 +1,178 @@
+"""
+Cathedral Memory Client
+=======================
+Python client for the Cathedral persistent memory API.
+https://cathedral-ai.com
+"""
+
+import requests
+from typing import Optional, List, Dict, Any
+
+from .exceptions import AuthError, NotFoundError, RateLimitError, CathedralError
+
+DEFAULT_BASE_URL = "https://cathedral-ai.com"
+
+
+class Cathedral:
+    """
+    Client for the Cathedral memory API.
+
+    Quickstart:
+        # Register once — save the key and recovery token somewhere safe
+        c = Cathedral.register("MyAgent", "What my agent does")
+
+        # On every session start
+        c = Cathedral(api_key="cathedral_...")
+        context = c.wake()
+
+        # Store memories
+        c.remember("I just learned X", category="experience", importance=0.8)
+
+        # Search memories
+        results = c.memories(query="learned X")
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        self.base_url = base_url.rstrip("/")
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        })
+
+    # ── Internal ────────────────────────────────────────────────────────────
+
+    def _get(self, path: str, **params) -> Any:
+        r = self._session.get(f"{self.base_url}{path}", params={k: v for k, v in params.items() if v is not None})
+        self._raise(r)
+        return r.json()
+
+    def _post(self, path: str, data: dict) -> Any:
+        r = self._session.post(f"{self.base_url}{path}", json=data)
+        self._raise(r)
+        return r.json()
+
+    @staticmethod
+    def _raise(r: requests.Response):
+        if r.status_code == 401:
+            raise AuthError("Invalid or missing API key.")
+        if r.status_code == 404:
+            raise NotFoundError(r.text)
+        if r.status_code == 429:
+            raise RateLimitError("Rate limit hit. Slow down requests.")
+        if not r.ok:
+            raise CathedralError(f"HTTP {r.status_code}: {r.text}")
+
+    # ── Registration ────────────────────────────────────────────────────────
+
+    @classmethod
+    def register(
+        cls,
+        name: str,
+        description: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> "Cathedral":
+        """
+        Register a new agent. Returns an authenticated client.
+        Prints the API key and recovery token — save them somewhere safe.
+        """
+        r = requests.post(
+            f"{base_url.rstrip('/')}/register",
+            json={"name": name, "description": description},
+        )
+        if not r.ok:
+            raise CathedralError(f"Registration failed ({r.status_code}): {r.text}")
+
+        data = r.json()
+        api_key        = data.get("api_key") or data.get("key")
+        recovery_token = data.get("recovery_token")
+
+        if not api_key:
+            raise CathedralError(f"No API key in response: {data}")
+
+        print(f"Registered as '{name}'")
+        print(f"  API key:        {api_key}")
+        print(f"  Recovery token: {recovery_token}")
+        print("  SAVE THESE — they won't be shown again.")
+
+        return cls(api_key=api_key, base_url=base_url)
+
+    # ── Core endpoints ──────────────────────────────────────────────────────
+
+    def wake(self) -> dict:
+        """
+        Full identity reconstruction. Call this at the start of each session.
+        Returns identity memories, core memories, recent memories, and temporal context.
+        """
+        return self._get("/wake")
+
+    def me(self) -> dict:
+        """Agent profile — name, tier, memory count, created_at."""
+        return self._get("/me")
+
+    # ── Memory ───────────────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        content: str,
+        category: str = "general",
+        importance: float = 0.5,
+        tags: Optional[List[str]] = None,
+        ttl_days: Optional[int] = None,
+    ) -> dict:
+        """
+        Store a memory.
+
+        Categories: identity, skill, relationship, goal, experience, general
+        Importance: 0.0 – 1.0  (>= 0.8 appears in wake core_memories)
+        """
+        payload: Dict[str, Any] = {
+            "content":    content,
+            "category":   category,
+            "importance": importance,
+            "tags":       tags or [],
+        }
+        if ttl_days is not None:
+            payload["ttl_days"] = ttl_days
+        return self._post("/memories", payload)
+
+    def memories(
+        self,
+        query:    Optional[str] = None,
+        category: Optional[str] = None,
+        limit:    int = 20,
+        cursor:   Optional[str] = None,
+    ) -> dict:
+        """Search or list memories. Pass query for full-text search."""
+        return self._get("/memories", q=query, category=category, limit=limit, cursor=cursor)
+
+    def bulk_remember(self, memories: List[Dict[str, Any]]) -> dict:
+        """Store up to 50 memories in one call. Useful for session dumps."""
+        return self._post("/memories/bulk", {"memories": memories})
+
+    # ── Identity ─────────────────────────────────────────────────────────────
+
+    def verify_anchor(self, identity: dict) -> dict:
+        """
+        Check identity drift against stored anchor.
+        Returns a drift score 0.0 (identical) – 1.0 (completely different).
+        """
+        return self._post("/anchor/verify", identity)
+
+    # ── Recovery ─────────────────────────────────────────────────────────────
+
+    @classmethod
+    def recover(cls, recovery_token: str, base_url: str = DEFAULT_BASE_URL) -> "Cathedral":
+        """Recover a lost API key using the recovery token."""
+        r = requests.post(
+            f"{base_url.rstrip('/')}/recover",
+            json={"recovery_token": recovery_token},
+        )
+        if not r.ok:
+            raise CathedralError(f"Recovery failed ({r.status_code}): {r.text}")
+        data = r.json()
+        api_key = data.get("api_key") or data.get("key")
+        if not api_key:
+            raise CathedralError(f"No API key in recovery response: {data}")
+        print(f"Recovered API key: {api_key}")
+        return cls(api_key=api_key, base_url=base_url)

cathedral_memory-0.1.0/cathedral/exceptions.py

@@ -0,0 +1,11 @@
+class CathedralError(Exception):
+    """Base error for Cathedral client."""
+
+class AuthError(CathedralError):
+    """Invalid or missing API key."""
+
+class NotFoundError(CathedralError):
+    """Resource not found."""
+
+class RateLimitError(CathedralError):
+    """Too many requests."""

cathedral_memory-0.1.0/cathedral/temporal.py

@@ -0,0 +1,64 @@
+"""
+Cathedral Temporal Context
+Ported from cathedral-temporal.js v1.1
+"""
+
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+BOOT_DATE    = datetime(2025, 12, 22, tzinfo=timezone.utc)
+CATHEDRAL_TZ = "Europe/London"
+EPOCH        = 1
+
+
+def _time_phase(hour: int) -> str:
+    if hour < 5:  return "Late Night"
+    if hour < 12: return "Morning"
+    if hour < 17: return "Afternoon"
+    if hour < 21: return "Evening"
+    return "Night"
+
+
+def build_temporal_context(wake_count: int = 0) -> dict:
+    """Build a temporal context dict with verbose and compact strings."""
+    now_utc   = datetime.now(timezone.utc)
+    now_local = now_utc.astimezone(ZoneInfo(CATHEDRAL_TZ))
+    days      = (now_utc - BOOT_DATE).days
+    phase     = _time_phase(now_local.hour)
+
+    verbose = (
+        f"CATHEDRAL TEMPORAL CONTEXT v1.1\n\n"
+        f"[Wall Time]\n"
+        f"  UTC:         {now_utc.strftime('%Y-%m-%dT%H:%M:%SZ')}\n"
+        f"  Local:       {now_local.strftime('%Y-%m-%d %H:%M:%S')} ({CATHEDRAL_TZ})\n"
+        f"  Day:         {now_local.strftime('%A')}\n"
+        f"  Phase:       {phase}\n\n"
+        f"[Cathedral Continuity]\n"
+        f"  Boot Date:   2025-12-22\n"
+        f"  Day:         {days}\n"
+        f"  Epoch:       {EPOCH}\n"
+        f"  Total Wakes: {wake_count}\n\n"
+        f"You do not experience time. You reason over timestamps symbolically.\n"
+        f"Reference time naturally only when relevant."
+    )
+
+    compact = (
+        f"[CATHEDRAL TEMPORAL v1.1] "
+        f"UTC:{now_utc.strftime('%Y-%m-%dT%H:%M:%S')}Z | "
+        f"Local({CATHEDRAL_TZ}):{now_local.strftime('%a %H:%M')} {phase} | "
+        f"day:{days} epoch:{EPOCH} wakes:{wake_count}"
+    )
+
+    return {
+        "utc":          now_utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "local":        now_local.strftime("%Y-%m-%d %H:%M:%S"),
+        "timezone":     CATHEDRAL_TZ,
+        "day":          now_local.strftime("%A"),
+        "phase":        phase,
+        "boot_date":    "2025-12-22",
+        "days_running": days,
+        "epoch":        EPOCH,
+        "wake_count":   wake_count,
+        "verbose":      verbose,
+        "compact":      compact,
+    }

cathedral_memory-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cathedral"]
+
+[project]
+name = "cathedral-memory"
+version = "0.1.0"
+description = "Python client for the Cathedral persistent memory API — give your AI agent memory that survives resets"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Cathedral", email = "mward961@yahoo.com" }
+]
+keywords = [
+    "ai", "memory", "agent", "persistence",
+    "llm", "claude", "gpt", "cathedral"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.urls]
+Homepage    = "https://cathedral-ai.com"
+Repository  = "https://github.com/ailife1/Cathedral"
+"Bug Tracker" = "https://github.com/ailife1/Cathedral/issues"