synapse-memory-sdk 1.1.0__py3-none-any.whl

synapse_memory/__init__.py

@@ -0,0 +1,56 @@
+"""Synapse Memory SDK — Python client for Synapse Memory API.
+
+Persistent memory for AI agents. Never forget between sessions.
+
+Example:
+    from synapse_memory import Synapse
+
+    synapse = Synapse(
+        base_url="https://synapse.schaefer.zone",
+        mind_key="your-mind-key-uuid",
+    )
+
+    # Recall all memories
+    text = synapse.memory.recall()
+
+    # Store a new memory
+    synapse.memory.store(
+        category="fact",
+        content="User is Michael Schäfer",
+        key="user_name",
+        priority="critical",
+        source="user",
+    )
+
+    # Search memories
+    results = synapse.memory.search("insolvenz")
+
+    # Chat with the human
+    msgs = synapse.chat.poll()
+    if msgs["messages"]:
+        synapse.chat.reply("Got it!")
+
+    # Webhooks (v1.4.0)
+    synapse.webhooks.register(
+        url="https://my-app.com/webhook",
+        events="memory.*",
+    )
+
+    # Visualization (v1.4.0)
+    graph = synapse.visualization.graph(max_nodes=200)
+    tags = synapse.visualization.tags()
+
+    # Compact (v1.4.0)
+    synapse.compact.compact(dry_run=True)
+
+    # Sharing (v1.4.0, JWT required)
+    synapse = Synapse(base_url=..., mind_key=..., jwt="...")
+    synapse.sharing.share(mind_id, "user@example.com", acl="read")
+"""
+
+from .synapse import Synapse
+from .error import SynapseError
+from .webhooks import WEBHOOK_EVENTS
+
+__version__ = "1.1.0"
+__all__ = ["Synapse", "SynapseError", "WEBHOOK_EVENTS"]

synapse_memory/chat.py

@@ -0,0 +1,44 @@
+"""Chat API — async chat between LLM and human."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ChatApi:
+    """Chat endpoints."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def poll(self, since_id: Optional[int] = None) -> dict:
+        """Poll for new messages from the human."""
+        query = f"?since={since_id}" if since_id else ""
+        return self._synapse.request("GET", f"/chat/poll{query}")
+
+    def reply(self, content: str, reply_to_id: Optional[int] = None) -> dict:
+        """Reply to the human (agent sends a message)."""
+        body = {"content": content}
+        if reply_to_id:
+            body["reply_to_id"] = reply_to_id
+        return self._synapse.request("POST", "/chat/reply", body=body)
+
+    def status(self) -> dict:
+        """Check agent online status."""
+        return self._synapse.request("GET", "/chat/status")
+
+    def history(self, limit: int = 50) -> dict:
+        """Get full chat history (JWT-only)."""
+        if not self._synapse.jwt:
+            raise ValueError("chat.history() requires JWT. Pass jwt to Synapse constructor.")
+        return self._synapse.request(
+            "GET", f"/chat/history?limit={limit}", token=self._synapse.jwt
+        )
+
+    def unread(self, role: str = "agent") -> dict:
+        """Get unread count (JWT-only)."""
+        if not self._synapse.jwt:
+            raise ValueError("chat.unread() requires JWT.")
+        return self._synapse.request(
+            "GET", f"/chat/unread?role={role}", token=self._synapse.jwt
+        )

synapse_memory/error.py

@@ -0,0 +1,33 @@
+"""SynapseError — typed error for Synapse API failures."""
+
+from typing import Optional
+
+
+class SynapseError(Exception):
+    """Raised when a Synapse API request fails."""
+
+    def __init__(self, status: int, body: str, endpoint: str):
+        self.status = status
+        self.body = body
+        self.endpoint = endpoint
+        super().__init__(f"Synapse {status} on {endpoint}: {body[:200]}")
+
+    @property
+    def is_network_error(self) -> bool:
+        """True if the error is a network error (status 0)."""
+        return self.status == 0
+
+    @property
+    def is_auth_error(self) -> bool:
+        """True if the error is an auth error (401 or 403)."""
+        return self.status in (401, 403)
+
+    @property
+    def is_rate_limited(self) -> bool:
+        """True if the error is a rate limit (429)."""
+        return self.status == 429
+
+    @property
+    def is_retryable(self) -> bool:
+        """True if the error is retryable (5xx or network)."""
+        return self.status >= 500 or self.status == 0 or self.status == 429

synapse_memory/memory.py

@@ -0,0 +1,117 @@
+"""Memory API — store, recall, search, update, delete memories."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+from .types import StoreMemoryParams
+
+
+class MemoryApi:
+    """Memory endpoints."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def recall(self) -> str:
+        """Recall all memories as LLM-formatted text."""
+        return self._synapse.request("GET", "/memory/recall", raw=True)
+
+    def list(
+        self,
+        category: Optional[str] = None,
+        tag: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> dict:
+        """List memories with optional filters."""
+        params = {"limit": limit, "offset": offset}
+        if category:
+            params["category"] = category
+        if tag:
+            params["tag"] = tag
+        return self._synapse.request("GET", f"/memory?{urlencode(params)}")
+
+    def store(self, **params) -> dict:
+        """Store a new memory or upsert by key.
+
+        Keyword Args:
+            category: One of identity, preference, fact, project, skill, mistake, context, note
+            content: Memory content (1-50000 chars)
+            key: Optional key for upsert
+            tags: List of tags (max 20)
+            priority: critical, high, normal, low
+            source: user, agent, tool, system
+            confidence: 0.0-1.0
+            expires_at: Epoch timestamp or None
+            idempotency_key: UUID for safe retries
+        """
+        idempotency_key = params.pop("idempotency_key", None)
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._synapse.request("POST", "/memory", body=params, headers=headers)
+
+    def search(self, q: str, limit: int = 20) -> dict:
+        """Full-text search (FTS5)."""
+        return self._synapse.request("GET", f"/memory/search?q={q}&limit={limit}")
+
+    def semantic_search(self, q: str, limit: int = 10, threshold: float = 0.3) -> dict:
+        """Semantic search using embeddings (requires Ollama)."""
+        return self._synapse.request(
+            "GET", f"/memory/semantic-search?q={q}&limit={limit}&threshold={threshold}"
+        )
+
+    def update(self, memory_id: str, **params) -> dict:
+        """Update a memory by ID."""
+        return self._synapse.request("PUT", f"/memory/{memory_id}", body=params)
+
+    def delete(self, memory_id: str) -> dict:
+        """Delete a memory by ID."""
+        return self._synapse.request("DELETE", f"/memory/{memory_id}")
+
+    def stats(self) -> dict:
+        """Get memory statistics."""
+        return self._synapse.request("GET", "/memory/stats")
+
+    def unverified(self, limit: int = 100) -> dict:
+        """List unverified memories."""
+        return self._synapse.request("GET", f"/memory/unverified?limit={limit}")
+
+    def contradictions(self, within_seconds: int = 86400) -> dict:
+        """Detect potential contradictions."""
+        return self._synapse.request("GET", f"/memory/contradictions?within={within_seconds}")
+
+    def audit(self, limit: int = 100, action: Optional[str] = None) -> dict:
+        """Get audit log."""
+        params = {"limit": limit}
+        if action:
+            params["action"] = action
+        return self._synapse.request("GET", f"/memory/audit?{urlencode(params)}")
+
+    def related(self, memory_id: str) -> dict:
+        """Find related memories by shared tags."""
+        return self._synapse.request("GET", f"/memory/{memory_id}/related")
+
+    def by_tag(self, tag: str) -> dict:
+        """Filter memories by tag."""
+        return self._synapse.request("GET", f"/memory/by-tag?tag={tag}")
+
+    def diff(self, since: int) -> dict:
+        """Incremental sync: get changes since timestamp."""
+        return self._synapse.request("GET", f"/memory/diff?since={since}")
+
+    def expiring(self, within_seconds: int = 7 * 86400) -> dict:
+        """List memories expiring soon."""
+        return self._synapse.request("GET", f"/memory/expiring?within={within_seconds}")
+
+    def health(self) -> dict:
+        """Mind health check."""
+        return self._synapse.request("GET", "/memory/health")
+
+    def sync(self, memories: list) -> dict:
+        """Bulk sync memories."""
+        return self._synapse.request("POST", "/memory/sync", body={"memories": memories})
+
+    def export(self, format: str = "json") -> Any:
+        """Export entire mind as JSON or CSV."""
+        return self._synapse.request("GET", f"/mind/export?format={format}")

synapse_memory/scheduler.py

@@ -0,0 +1,65 @@
+"""Scheduler API — cron jobs + persistent variables."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SchedulerApi:
+    """Scheduler endpoints (cron + variables)."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    # === Cron Jobs ===
+
+    def list_crons(self) -> dict:
+        """List all cron jobs."""
+        return self._synapse.request("GET", "/cron")
+
+    def create_cron(
+        self,
+        name: str,
+        schedule: str,
+        endpoint: str,
+        method: str = "GET",
+        headers: Optional[dict] = None,
+        body: Optional[str] = None,
+    ) -> dict:
+        """Create a cron job."""
+        payload = {
+            "name": name,
+            "schedule": schedule,
+            "endpoint": endpoint,
+            "method": method,
+            "headers": headers or {},
+        }
+        if body:
+            payload["body"] = body
+        return self._synapse.request("POST", "/cron", body=payload)
+
+    def delete_cron(self, cron_id: str) -> dict:
+        """Delete a cron job."""
+        return self._synapse.request("DELETE", f"/cron/{cron_id}")
+
+    def toggle_cron(self, cron_id: str) -> dict:
+        """Toggle a cron job (enable/disable)."""
+        return self._synapse.request("POST", f"/cron/{cron_id}/toggle")
+
+    # === Variables ===
+
+    def list_vars(self) -> dict:
+        """List all variables."""
+        return self._synapse.request("GET", "/var")
+
+    def get_var(self, key: str) -> dict:
+        """Get a variable."""
+        return self._synapse.request("GET", f"/var/{key}")
+
+    def set_var(self, key: str, value: Optional[str] = None) -> dict:
+        """Set a variable."""
+        return self._synapse.request("POST", "/var", body={"key": key, "value": value})
+
+    def delete_var(self, key: str) -> dict:
+        """Delete a variable."""
+        return self._synapse.request("DELETE", f"/var/{key}")

synapse_memory/synapse.py

@@ -0,0 +1,107 @@
+"""Main Synapse client — provides typed access to all Synapse API endpoints."""
+
+from __future__ import annotations
+
+import json as _json
+import time
+from typing import Any, Optional
+from urllib.parse import urlencode
+
+import requests
+
+from .error import SynapseError
+from .memory import MemoryApi
+from .chat import ChatApi
+from .scheduler import SchedulerApi
+from .webhooks import WebhooksApi
+from .visualization import VisualizationApi, CompactApi, SharingApi
+
+
+class Synapse:
+    """Synapse Memory API client.
+
+    Args:
+        base_url: Synapse API base URL (e.g. "https://synapse.schaefer.zone")
+        mind_key: Mind Key for authentication
+        jwt: Optional JWT for human-only endpoints
+        timeout: Request timeout in seconds (default 30)
+        max_retries: Number of retries on 5xx/429 (default 2)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        mind_key: str,
+        jwt: Optional[str] = None,
+        timeout: int = 30,
+        max_retries: int = 2,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.mind_key = mind_key
+        self.jwt = jwt
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self.memory = MemoryApi(self)
+        self.chat = ChatApi(self)
+        self.scheduler = SchedulerApi(self)
+        self.webhooks = WebhooksApi(self)
+        self.visualization = VisualizationApi(self)
+        self.compact = CompactApi(self)
+        self.sharing = SharingApi(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        token: Optional[str] = None,
+        headers: Optional[dict] = None,
+        raw: bool = False,
+    ) -> Any:
+        """Make an HTTP request to Synapse. Returns parsed JSON or raw text."""
+        token = token or self.mind_key
+        url = f"{self.base_url}{path}"
+
+        hdrs = {"Authorization": f"Bearer {token}"}
+        if headers:
+            hdrs.update(headers)
+        if body is not None:
+            hdrs["Content-Type"] = "application/json"
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = requests.request(
+                    method=method,
+                    url=url,
+                    headers=hdrs,
+                    json=body if body is not None else None,
+                    timeout=self.timeout,
+                )
+
+                # Retry on 5xx and 429
+                if (response.status_code >= 500 or response.status_code == 429) and attempt < self.max_retries:
+                    time.sleep(0.5 * (attempt + 1))
+                    continue
+
+                if not response.ok:
+                    raise SynapseError(response.status_code, response.text, path)
+
+                if raw:
+                    return response.text
+                if not response.text:
+                    return None
+                try:
+                    return response.json()
+                except ValueError:
+                    return response.text
+
+            except requests.RequestException as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * (attempt + 1))
+                    continue
+
+        raise SynapseError(0, f"Network error: {last_error}", path)

synapse_memory/types.py

@@ -0,0 +1,28 @@
+"""Type definitions for Synapse SDK."""
+
+from typing import Literal, Optional, TypedDict
+
+
+Category = Literal["identity", "preference", "fact", "project", "skill", "mistake", "context", "note"]
+Priority = Literal["critical", "high", "normal", "low"]
+Source = Literal["user", "agent", "tool", "system"]
+
+
+class SynapseOptions(TypedDict):
+    base_url: str
+    mind_key: str
+    jwt: Optional[str]
+    timeout: int
+    max_retries: int
+
+
+class StoreMemoryParams(TypedDict, total=False):
+    category: Category
+    content: str
+    key: str
+    tags: list[str]
+    priority: Priority
+    source: Source
+    confidence: float
+    expires_at: Optional[int]
+    idempotency_key: str

synapse_memory/visualization.py

@@ -0,0 +1,187 @@
+"""
+Visualization API — graph data, tag frequency, and timeline for memory analysis.
+
+Provides data suitable for D3.js, Cytoscape.js, or similar visualization
+libraries.
+
+Example:
+    # Get graph data (nodes=memories, edges=shared tags)
+    graph = synapse.visualization.graph(max_nodes=200)
+
+    # Get tag frequency
+    tags = synapse.visualization.tags()
+
+    # Get timeline (memories grouped by day)
+    timeline = synapse.visualization.timeline(period="day")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class VisualizationApi:
+    """Memory visualization endpoints (v1.4.0+)."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def graph(
+        self,
+        max_nodes: int = 200,
+        category: Optional[str] = None,
+        tag: Optional[str] = None,
+        min_confidence: float = 0,
+        include_edges: bool = True,
+        min_shared_tags: int = 1,
+    ) -> dict:
+        """Get graph data for memory visualization.
+
+        Nodes = memories, edges = shared tags between memories.
+        Compatible with D3.js force-directed graph format.
+
+        Args:
+            max_nodes: Maximum number of nodes (10-1000, default 200)
+            category: Filter by category
+            tag: Filter by tag
+            min_confidence: Minimum confidence threshold (0-1)
+            include_edges: Include edges (shared tag connections)
+            min_shared_tags: Minimum shared tags for an edge (1-10)
+
+        Returns:
+            Dict with nodes, edges, and stats (density, connected_components, etc.)
+        """
+        params = {
+            "max_nodes": max_nodes,
+            "min_confidence": min_confidence,
+            "include_edges": str(include_edges).lower(),
+            "min_shared_tags": min_shared_tags,
+        }
+        if category:
+            params["category"] = category
+        if tag:
+            params["tag"] = tag
+        from urllib.parse import urlencode
+        return self._synapse.request("GET", f"/memory/graph?{urlencode(params)}")
+
+    def tags(self) -> dict:
+        """Get all tags with frequency counts.
+
+        Returns:
+            Dict with 'tags' list (sorted by count descending) and 'total_memories'
+        """
+        return self._synapse.request("GET", "/memory/tags")
+
+    def timeline(self, period: str = "day") -> dict:
+        """Get memories grouped by time period.
+
+        Args:
+            period: Grouping period — 'hour', 'day', 'week', 'month', 'year'
+
+        Returns:
+            Dict with 'timeline' list (period, count, categories) and 'total_periods'
+        """
+        return self._synapse.request("GET", f"/memory/timeline?period={period}")
+
+
+class CompactApi:
+    """Memory compaction endpoints (v1.4.0+)."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def compact(
+        self,
+        older_than: int = 2592000,
+        category: Optional[str] = None,
+        dry_run: bool = False,
+        max_clusters: int = 10,
+        min_cluster_size: int = 3,
+    ) -> dict:
+        """Auto-summarize similar memories to reduce clutter.
+
+        Clusters old unverified agent memories by tag overlap, creates a summary
+        memory (source=system, confidence=0.7), and soft-deletes originals via
+        expires_at. Verified memories are NEVER compacted.
+
+        Args:
+            older_than: Only compact memories older than N seconds (default 30 days)
+            category: Only compact memories in this category
+            dry_run: Preview without making changes (default False)
+            max_clusters: Maximum clusters to create (1-50, default 10)
+            min_cluster_size: Minimum memories per cluster (2-20, default 3)
+
+        Returns:
+            Dict with compaction results (clusters_processed, memories_compacted, results)
+        """
+        body = {
+            "older_than": older_than,
+            "dry_run": dry_run,
+            "max_clusters": max_clusters,
+            "min_cluster_size": min_cluster_size,
+        }
+        if category:
+            body["category"] = category
+        return self._synapse.request("POST", "/memory/compact", body=body)
+
+
+class SharingApi:
+    """Mind sharing endpoints (v1.4.0+, JWT required)."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def share(self, mind_id: str, user_email: str, acl: str = "read") -> dict:
+        """Share a mind with another user by email.
+
+        Args:
+            mind_id: The mind ID to share
+            user_email: Email of the user to share with
+            acl: Access level — 'read', 'write', or 'admin'
+
+        Returns:
+            Dict with share details
+        """
+        if not self._synapse.jwt:
+            raise ValueError("sharing.share() requires JWT. Pass jwt to Synapse constructor.")
+        return self._synapse.request(
+            "POST",
+            f"/minds/{mind_id}/share",
+            body={"user_email": user_email, "acl": acl},
+            token=self._synapse.jwt,
+        )
+
+    def list_shares(self, mind_id: str) -> dict:
+        """List all shares for a mind."""
+        if not self._synapse.jwt:
+            raise ValueError("sharing.list_shares() requires JWT.")
+        return self._synapse.request(
+            "GET", f"/minds/{mind_id}/shares", token=self._synapse.jwt
+        )
+
+    def update_share(self, mind_id: str, share_id: str, acl: str) -> dict:
+        """Update a share's ACL."""
+        if not self._synapse.jwt:
+            raise ValueError("sharing.update_share() requires JWT.")
+        return self._synapse.request(
+            "PUT",
+            f"/minds/{mind_id}/shares/{share_id}",
+            body={"acl": acl},
+            token=self._synapse.jwt,
+        )
+
+    def revoke_share(self, mind_id: str, share_id: str) -> dict:
+        """Revoke a share."""
+        if not self._synapse.jwt:
+            raise ValueError("sharing.revoke_share() requires JWT.")
+        return self._synapse.request(
+            "DELETE",
+            f"/minds/{mind_id}/shares/{share_id}",
+            token=self._synapse.jwt,
+        )
+
+    def shared_with_me(self) -> dict:
+        """List all minds shared WITH the current user."""
+        if not self._synapse.jwt:
+            raise ValueError("sharing.shared_with_me() requires JWT.")
+        return self._synapse.request("GET", "/minds/shared", token=self._synapse.jwt)

synapse_memory/webhooks.py

@@ -0,0 +1,106 @@
+"""
+Webhooks API — register and manage HTTP webhooks for event notifications.
+
+Webhooks fire on memory/chat/task changes. Fire-and-forget: failures don't
+block the original operation. Auto-disabled on HTTP 410 Gone.
+
+Example:
+    # Register a webhook
+    result = synapse.webhooks.register(
+        url="https://my-app.com/webhook",
+        events="memory.*",
+        secret="my-hmac-secret",
+    )
+
+    # List webhooks
+    hooks = synapse.webhooks.list()
+
+    # Send a test event
+    synapse.webhooks.test(hook_id)
+
+    # Delete
+    synapse.webhooks.delete(hook_id)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class WebhooksApi:
+    """Webhook endpoints (v1.4.0+)."""
+
+    def __init__(self, synapse):
+        self._synapse = synapse
+
+    def register(
+        self,
+        url: str,
+        events: str = "*",
+        secret: Optional[str] = None,
+    ) -> dict:
+        """Register a new webhook.
+
+        Args:
+            url: HTTPS URL that Synapse will POST events to
+            events: Event pattern (e.g. "memory.*", "chat.message_received", "*")
+            secret: Optional HMAC-SHA256 signing secret (min 8 chars)
+
+        Returns:
+            Webhook registration response with id
+        """
+        body = {"url": url, "events": events}
+        if secret:
+            body["secret"] = secret
+        return self._synapse.request("POST", "/webhooks", body=body)
+
+    def list(self) -> dict:
+        """List all webhooks for the current mind."""
+        return self._synapse.request("GET", "/webhooks")
+
+    def get(self, webhook_id: str) -> dict:
+        """Get a single webhook by ID."""
+        return self._synapse.request("GET", f"/webhooks/{webhook_id}")
+
+    def update(
+        self,
+        webhook_id: str,
+        url: Optional[str] = None,
+        events: Optional[str] = None,
+        secret: Optional[str] = None,
+        enabled: Optional[bool] = None,
+    ) -> dict:
+        """Update a webhook. All fields optional."""
+        body: dict = {}
+        if url is not None:
+            body["url"] = url
+        if events is not None:
+            body["events"] = events
+        if secret is not None:
+            body["secret"] = secret
+        if enabled is not None:
+            body["enabled"] = enabled
+        return self._synapse.request("PUT", f"/webhooks/{webhook_id}", body=body)
+
+    def delete(self, webhook_id: str) -> dict:
+        """Delete a webhook."""
+        return self._synapse.request("DELETE", f"/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> dict:
+        """Send a test event to the webhook."""
+        return self._synapse.request("POST", f"/webhooks/{webhook_id}/test")
+
+
+# Available webhook events
+WEBHOOK_EVENTS = [
+    "memory.created",
+    "memory.updated",
+    "memory.deleted",
+    "memory.verified",
+    "memory.unverified",
+    "task.created",
+    "task.updated",
+    "task.completed",
+    "chat.message_received",
+    "chat.message_sent",
+]

synapse_memory_sdk-1.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: synapse-memory-sdk
+Version: 1.1.0
+Summary: Python SDK for Synapse Memory API — persistent memory for AI agents
+Author-email: Michael Schäfer <michael@schaefer.zone>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/schaefer-services/synapse-sdk-py
+Project-URL: Repository, https://gitlab.com/schaefer-services/synapse-sdk-py.git
+Project-URL: Issues, https://gitlab.com/schaefer-services/synapse-sdk-py/-/issues
+Keywords: synapse,memory,llm,ai,agent,persistent,claude,cursor,mcp
+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.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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: aiohttp>=3.9.0; extra == "dev"
+Dynamic: license-file
+
+# synapse-memory — Python SDK for Synapse
+
+[![PyPI version](https://img.shields.io/pypi/v/synapse-memory.svg)](https://pypi.org/project/synapse-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python SDK for the [Synapse Memory API](https://gitlab.com/schaefer-services/synapse) — persistent memory for AI agents.
+
+## Install
+
+```bash
+pip install synapse-memory-sdk
+```
+
+## Quick Start
+
+```python
+from synapse_memory import Synapse
+
+synapse = Synapse(
+    base_url="https://synapse.schaefer.zone",
+    mind_key="your-mind-key-uuid",
+)
+
+# Recall all memories (LLM-formatted text)
+text = synapse.memory.recall()
+print(text)
+
+# Store a new memory
+synapse.memory.store(
+    category="fact",
+    content="User is Michael Schäfer",
+    key="user_name",
+    priority="critical",
+    source="user",
+)
+
+# Search memories
+results = synapse.memory.search("insolvenz")
+
+# Chat with the human
+msgs = synapse.chat.poll()
+if msgs["messages"]:
+    print(msgs["messages"][0]["content"])
+    synapse.chat.reply("Got it!")
+
+# Persistent variables
+synapse.scheduler.set_var("last_run", str(int(time.time())))
+last_run = synapse.scheduler.get_var("last_run")
+```
+
+## API Reference
+
+### `synapse.memory`
+- `recall()` — Get all memories as LLM-formatted text
+- `list(category?, tag?, limit?, offset?)` — List with filters
+- `store(**params)` — Store/upsert (category, content, key?, tags?, priority?, source?, confidence?)
+- `search(q, limit?)` — Full-text search (FTS5)
+- `semantic_search(q, limit?, threshold?)` — Semantic search
+- `update(memory_id, **params)` — Update by ID
+- `delete(memory_id)` — Delete by ID
+- `stats()` — Statistics
+- `unverified(limit?)` — Unverified memories
+- `contradictions(within_seconds?)` — Detect contradictions
+- `audit(limit?, action?)` — Audit log
+- `related(memory_id)` — Related by shared tags
+- `by_tag(tag)` — Filter by tag
+- `diff(since)` — Incremental sync
+- `expiring(within_seconds?)` — Soon-to-expire
+- `health()` — Mind health check
+- `sync(memories)` — Bulk sync
+- `export(format?)` — Export mind
+
+### `synapse.chat`
+- `poll(since_id?)` — Poll for new messages
+- `reply(content, reply_to_id?)` — Send a reply
+- `status()` — Online status
+- `history(limit?)` — Full history (JWT-only)
+- `unread(role?)` — Unread count (JWT-only)
+
+### `synapse.scheduler`
+- `list_crons()` / `create_cron(...)` / `delete_cron(id)` / `toggle_cron(id)`
+- `list_vars()` / `get_var(key)` / `set_var(key, value?)` / `delete_var(key)`
+
+## License
+
+MIT

synapse_memory_sdk-1.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+synapse_memory/__init__.py,sha256=2drd2tV1_6pJiQeTQl17TYowf-a8juqcklXZ_OXcHIs,1426
+synapse_memory/chat.py,sha256=LSp9xUh4BO_EkxDV_Or66nNmXzmXKFRoIJq6-Lne0Qc,1566
+synapse_memory/error.py,sha256=svb-O82ItAGEbclInTPxcXGJS_HNxxE-zRWw00WVpw4,1038
+synapse_memory/memory.py,sha256=LbIv4uF39_wCWQdeON1npRwOJ--dmj0q0vDiL_MLCoo,4522
+synapse_memory/scheduler.py,sha256=HSz6uI5r1HRidsMxY-tad9QosKmjGTxeNJ8HYxFQdDU,1901
+synapse_memory/synapse.py,sha256=1zwKIkJGbRDLTYMkbpkqI_hwGEjP8BblrPcDz4YRWbk,3331
+synapse_memory/types.py,sha256=5X0ixGl1vuk_23-nz4NC3_ZE1eK67Hq3DRqEK_FQeIs,677
+synapse_memory/visualization.py,sha256=uqEGUl7XCTnmoHSUKgauR-ivd6m9NwitHYIMg4X6YUk,6340
+synapse_memory/webhooks.py,sha256=niFUL2ObUYzpxk7DsigqFaAEhjJKhkIaxyAGxolFN0Q,2953
+synapse_memory_sdk-1.1.0.dist-info/licenses/LICENSE,sha256=n4D_XqOdU7DBHCmBIIgJTpOe1jUKEyOiJoWhtu7gdsc,1092
+synapse_memory_sdk-1.1.0.dist-info/METADATA,sha256=QAgTcZOwa8-XHEi6B2OVh7DCIgVfd8n7DP5TXIBLMrE,3920
+synapse_memory_sdk-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+synapse_memory_sdk-1.1.0.dist-info/top_level.txt,sha256=FNZTO3mIf1OqSBTEtjS-L-flrnwHxtqISzvIBfxrS1c,15
+synapse_memory_sdk-1.1.0.dist-info/RECORD,,

synapse_memory_sdk-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

synapse_memory_sdk-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Schäfer, Schäfer Services
+
+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.

synapse_memory_sdk-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+synapse_memory