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
