# Octopoda: Persistent Memory for AI Agents

**Your agents remember everything. Crash-safe. Sub-millisecond. Framework-agnostic.**

[![License](https://img.shields.io/badge/license-MIT%20%2F%20Proprietary-lightgrey)](LICENSE)

## Install

```bash
pip install octopoda
```

## Quick Start

```python
from octopoda import AgentRuntime

agent = AgentRuntime("my_agent", agent_type="researcher")
agent.remember("user_preference", {"format": "bullet_points"})
result = agent.recall("user_preference")
print(result.value)  # {"format": "bullet_points"}
```

That's it. Memory persists across crashes, restarts, and deployments.

## Why Octopoda?

AI agents lose memory on every restart. Octopoda fixes that:

- **Persistent memory** — SQLite-backed by default, optional high-performance C lattice engine
- **Crash recovery** — Automatic snapshots, sub-millisecond restore
- **Shared memory bus** — Agents share knowledge across processes
- **Full audit trail** — Every decision logged with memory context
- **Framework integrations** — LangChain, CrewAI, AutoGen, OpenAI Agents SDK
- **Cloud API** — FastAPI REST API with auth, rate limiting, Swagger docs
- **Real-time dashboard** — Monitor agents, memory, performance, anomalies

## Framework Integrations

### LangChain

```python
from synrix_runtime.integrations.langchain_memory import SynrixMemory
memory = SynrixMemory(agent_id="my_chain")
# Use with: ConversationChain(llm=llm, memory=memory)
```

### CrewAI

```python
from synrix_runtime.integrations.crewai_memory import SynrixCrewMemory
crew_memory = SynrixCrewMemory(crew_id="research_crew")
crew_memory.store_finding("researcher", "market_size", {"value": "$4.2B"})
```

### AutoGen

```python
from synrix_runtime.integrations.autogen_memory import SynrixAutoGenMemory
memory = SynrixAutoGenMemory(group_id="dev_team")
memory.store_message("alice", "bob", "The API is ready")
```

### OpenAI Agents SDK

```python
from synrix_runtime.integrations.openai_agents import SynrixOpenAIMemory
memory = SynrixOpenAIMemory()
memory.store_thread_state("thread_123", {"messages": [...]})
```

## MCP Server (Claude, Cursor, ChatGPT, VS Code)

Give any MCP-compatible AI persistent memory with zero code. One config entry and your AI remembers everything.

```bash
pip install octopoda
```

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "octopoda": {
      "command": "octopoda-mcp"
    }
  }
}
```

That's it. Claude now has 10 memory tools: `octopoda_remember`, `octopoda_recall`, `octopoda_search`, `octopoda_snapshot`, `octopoda_restore`, `octopoda_share`, `octopoda_read_shared`, `octopoda_list_agents`, `octopoda_agent_stats`, `octopoda_log_decision`.

Works with any MCP client: Claude Desktop, Cursor, VS Code, ChatGPT, and more.

## Docker

```bash
docker compose up
```

The dashboard is at `http://localhost:7842`, the API at `http://localhost:8741/docs`.

## Cloud API

The REST API runs on port 8741 with auto-generated Swagger docs at `/docs`.

```bash
# Remember
curl -X POST http://localhost:8741/v1/agents/my_agent/remember \
  -H "Content-Type: application/json" \
  -d '{"key": "task_result", "value": {"status": "complete"}}'

# Recall
curl http://localhost:8741/v1/agents/my_agent/recall/task_result
```

## Configuration

All configuration via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `SYNRIX_BACKEND` | `sqlite` | Backend: `sqlite`, `lattice`, `auto` |
| `SYNRIX_DATA_DIR` | `~/.synrix/data` | Data directory |
| `SYNRIX_API_PORT` | `8741` | Cloud API port |
| `SYNRIX_DASHBOARD_PORT` | `7842` | Dashboard port |
| `SYNRIX_API_KEY` | *(empty)* | API key for auth |
| `SYNRIX_LOG_LEVEL` | `INFO` | Logging level |
| `SYNRIX_GC_ENABLED` | `true` | Enable garbage collection |
| `SYNRIX_GC_INTERVAL_HOURS` | `6` | GC cycle interval |
| `SYNRIX_GC_METRICS_DAYS` | `7` | Metrics retention (days) |
| `SYNRIX_GC_EVENTS_DAYS` | `14` | Events retention (days) |
| `SYNRIX_GC_AUDIT_DAYS` | `90` | Audit trail retention (days) |

## Architecture

```
octopoda (public API)
  └── synrix_runtime (runtime layer)
        ├── api/          — AgentRuntime, Cloud API (FastAPI), MCP Server, shared memory
        ├── core/         — Daemon, heartbeat, recovery, garbage collection
        ├── monitoring/   — Metrics, anomaly detection, audit, performance
        ├── integrations/ — LangChain, CrewAI, AutoGen, OpenAI
        └── dashboard/    — Flask dashboard with SSE real-time streaming
  └── synrix (SDK layer)
        ├── agent_backend — Backend abstraction (SQLite, Lattice, Mock)
        ├── sqlite_client — SQLite implementation
        ├── memory        — High-level Memory API
        └── licensing     — Tier enforcement
```

## Platform Support

| Platform | Status |
|----------|--------|
| Linux x86_64 | Ready |
| Linux ARM64 (Jetson, Pi) | Ready |
| Windows x86_64 | Ready |
| macOS (Apple Silicon) | Ready (SQLite backend) |

## License

- **Python SDK + Runtime**: MIT (fully open)
- **Lattice Engine (libsynrix)**: Proprietary (optional, for high-performance workloads)

---

**Octopoda** — Persistent memory for AI agents. Install, import, ship.
