# Kronvex Python SDK v0.3.0

Persistent memory layer for AI agents — REST API wrapper with sync + async support.

## Install

```bash
pip install kronvex          # sync only (zero deps)
pip install kronvex[async]   # + async support via httpx
```

## Quick start

```python
from kronvex import Kronvex

kx = Kronvex(api_key="kx_live_...", agent_id="<uuid>")

# Store a memory
kx.remember("User prefers concise answers and uses Python 3.11")

# Recall relevant memories
results = kx.recall("user coding preferences")
for r in results:
    print(f"[{r.confidence:.2f}] {r.memory.content}")

# Inject context into your prompt
ctx = kx.inject_context("What language should I use?")
system_prompt = str(ctx) + "\n\nYou are a helpful assistant."
```

## Environment variables

```bash
export KRONVEX_API_KEY="kx_live_..."
export KRONVEX_AGENT_ID="<uuid>"
```

```python
kx = Kronvex()  # reads from env
```

## TTL & pinned memories (v0.3.0)

```python
# Memory expires in 30 days
kx.remember("Temporary session note", ttl_days=30)

# Pinned memory never expires
kx.remember("User's name is Alice", pinned=True)

# Confidence score on recall results
results = kx.recall("user name")
print(results.best().confidence)  # 0.0–1.0 composite score
```

## Session filtering

```python
# Store with session
kx.remember("User asked about pricing", session_id="session_abc")

# Recall within session only
results = kx.recall("pricing questions", session_id="session_abc")

# List all sessions
sessions = kx.list_sessions()
# [{"session_id": "session_abc", "count": 12}, ...]
```

## Async (FastAPI, async frameworks)

```python
from kronvex import AsyncKronvex

async def handler(user_message: str):
    async with AsyncKronvex(api_key="kx_live_...", agent_id="<uuid>") as kx:
        ctx = await kx.inject_context(user_message)
        return str(ctx)
```

## Full API

| Method | Description |
|--------|-------------|
| `remember(content, *, memory_type, session_id, metadata, ttl_days, pinned)` | Store a memory |
| `recall(query, *, top_k, threshold, session_id, memory_type)` | Semantic recall |
| `inject_context(message, *, top_k, threshold)` | Context block for system prompt |
| `create_agent(name, description)` | Create a new agent |
| `list_agents()` | List all agents |
| `list_sessions(agent_id)` | List session IDs with memory counts |
| `delete_memory(memory_id)` | Delete one memory |

## Error handling

```python
from kronvex import Kronvex, AuthError, RateLimitError, KronvexError

try:
    kx.remember("...")
except AuthError:
    print("Invalid API key")
except RateLimitError:
    print("Slow down!")
except KronvexError as e:
    print(f"API error {e.status_code}: {e}")
```

## Links

- [Dashboard](https://kronvex.io/dashboard)
- [API docs](https://api.kronvex.io/docs)
- [Changelog](https://kronvex.io/changelog)
- hello@kronvex.io
