Metadata-Version: 2.4
Name: octopoda
Version: 2.0.8
Summary: Persistent Memory Kernel for AI Agents — crash recovery, shared memory, audit trail, real-time dashboard
Author-email: RYJOX Technologies <ryjoxtechnologies@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/RYJOX-Technologies/Octopoda
Project-URL: Documentation, https://github.com/RYJOX-Technologies/Octopoda#readme
Project-URL: Repository, https://github.com/RYJOX-Technologies/Octopoda
Keywords: ai-memory,agent-memory,persistent-memory,langchain,crewai,autogen,openai-agents,crash-recovery,multi-agent,memory-kernel,semantic-search,knowledge-graph,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
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: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: flask>=2.3.0
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: client
Requires-Dist: requests>=2.28.0; extra == "client"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Requires-Dist: langchain-community>=0.1.0; extra == "langchain"
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: ai
Requires-Dist: sentence-transformers>=2.0.0; extra == "ai"
Requires-Dist: numpy>=1.21.0; extra == "ai"
Provides-Extra: search
Requires-Dist: faiss-cpu>=1.7.0; extra == "search"
Requires-Dist: numpy>=1.21.0; extra == "search"
Provides-Extra: nlp
Requires-Dist: spacy>=3.5.0; extra == "nlp"
Provides-Extra: all-ai
Requires-Dist: sentence-transformers>=2.0.0; extra == "all-ai"
Requires-Dist: numpy>=1.21.0; extra == "all-ai"
Requires-Dist: spacy>=3.5.0; extra == "all-ai"
Requires-Dist: faiss-cpu>=1.7.0; extra == "all-ai"
Provides-Extra: telemetry
Requires-Dist: psutil>=5.9.0; extra == "telemetry"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Octopoda

### Persistent memory for AI agents. Store, search, and share knowledge across crashes, restarts, and deployments.

[![PyPI](https://img.shields.io/pypi/v/octopoda-memory)](https://pypi.org/project/octopoda-memory/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-215%20passing-brightgreen)]()

---

## The Problem

Every AI agent framework has the same gap: **agents forget everything when they restart.** Chat history vanishes. Learned preferences disappear. Context built over hours of conversation is gone.

Developers end up duct-taping together vector databases, key-value stores, and custom serialization. It works until it doesn't — no versioning, no search, no crash recovery, no way for agents to share what they've learned.

## The Solution

```bash
pip install octopoda-memory
```

```python
from octopoda import AgentRuntime

agent = AgentRuntime("my_agent")
agent.remember("user_pref", "Alice is vegetarian and lives in London")

# Search by meaning, not just keys
results = agent.recall_similar("what food does the user like?")
# Returns: "Alice is vegetarian and lives in London" (score: 0.79)
```

Three lines. Memory persists forever. Works with any framework or none at all.

---

## What Makes Octopoda Different

| | Octopoda | Mem0 | Raw Vector DB | Framework Memory |
|---|---|---|---|---|
| Runs 100% locally | Yes | No (cloud) | Depends | Yes |
| Semantic search | Yes (0.87+ with LLM) | Yes | Yes | No |
| Fact extraction | Yes (auto-decomposes text) | No | No | No |
| Knowledge graph | Yes (SQLite, no Neo4j) | No | No | No |
| Temporal versioning | Yes (full history) | No | No | No |
| Crash recovery | Yes (sub-ms restore) | N/A | No | No |
| Cross-agent sharing | Yes (shared memory pools) | Limited | No | No |
| Multi-tenant cloud API | Yes (FastAPI + auth) | Paid tier | No | No |
| MCP server | Yes (13 tools) | No | No | No |
| Framework integrations | LangChain, CrewAI, AutoGen, OpenAI | Some | None | Own framework only |
| Price | Free, forever | Freemium | Varies | Free |

---

## Features

### Semantic Search

Find memories by meaning, not just exact keys. Uses `bge-small-en-v1.5` — a 33MB model that runs on any CPU.

```bash
pip install octopoda-memory[ai]  # Adds local embeddings
```

```python
agent.remember("bio", "Alice is a vegetarian living in London")
agent.remember("work", "Alice is a senior engineer at Google")
agent.remember("hobby", "Alice runs marathons on weekends")

results = agent.recall_similar("where does the user work?")
# Returns: "Alice is a senior engineer at Google" (score: 0.82)

results = agent.recall_similar("outdoor activities")
# Returns: "Alice runs marathons on weekends" (score: 0.79)
```

### Fact Extraction (LLM-Powered)

Out of the box, semantic search scores ~0.53. Good, but not great. Enable any LLM and Octopoda automatically decomposes memories into individual tagged facts, pushing search accuracy to **0.87+**.

```python
agent.remember("meeting", "Alice said Q2 revenue hit $4.2M and we need to hire 3 engineers by March")

# Without fact extraction: stored as one blob
# With fact extraction: decomposed into individual facts:
#   - "Q2 revenue reached $4.2M (financial, quarterly results)"
#   - "Need to hire 3 engineers by March (hiring, staffing, deadline)"
#   - "Alice reported on Q2 results (person, meeting)"
#
# Now searching "hiring plans" returns the specific fact, not the whole paragraph.
```

Configure in one line:

```bash
# OpenAI
export OCTOPODA_LLM_PROVIDER=openai
export OCTOPODA_OPENAI_API_KEY=sk-...

# Or Anthropic
export OCTOPODA_LLM_PROVIDER=anthropic
export OCTOPODA_ANTHROPIC_API_KEY=sk-ant-...

# Or ANY OpenAI-compatible API (Groq, Together, Mistral, local)
export OCTOPODA_LLM_PROVIDER=openai
export OCTOPODA_OPENAI_API_KEY=gsk_...
export OCTOPODA_OPENAI_BASE_URL=https://api.groq.com/openai/v1

# Or local Ollama (free, no API key)
export OCTOPODA_LLM_PROVIDER=ollama
```

No LLM configured? Everything still works — memories are embedded and searchable, just at baseline accuracy.

### Knowledge Graph

Octopoda auto-extracts entities and relationships from stored memories using spaCy NER and SVO triple extraction. No Neo4j, no setup — it's all in SQLite.

```bash
pip install octopoda-memory[nlp]  # Adds spaCy
```

```python
agent.remember("team", "Alice manages the London engineering team with Bob and Carol")

# Auto-extracted: Alice -> manages -> London engineering team
#                 Bob -> member_of -> London engineering team
#                 Carol -> member_of -> London engineering team

related = agent.related("Alice")
# Returns entity graph with relationships
```

### Temporal Versioning

Track how facts change over time. Full version history with valid_from/valid_until timestamps.

```python
agent.remember("status", "Project is in planning phase")
# ... weeks later ...
agent.remember("status", "Project launched to production")

history = agent.recall_history("status")
# Returns both versions with timestamps — see exactly when things changed
```

### Crash Recovery

Automatic snapshots with sub-millisecond restore. Your agents pick up exactly where they left off.

```python
agent.snapshot("before_migration")
# ... something goes wrong ...
agent.restore("before_migration")  # instant recovery
```

### Shared Memory

Agents share knowledge across processes without stepping on each other.

```python
# Agent A stores a finding
agent_a.share("research_pool", "competitor_analysis", {"findings": "..."})

# Agent B reads it from a completely different process
data = agent_b.read_shared("research_pool", "competitor_analysis")
```

---

## Cloud API

Run a production-ready REST API with multi-tenant auth, rate limiting, and per-tenant isolation.

```bash
octopoda --api-port 8000
```

```bash
# Sign up
curl -X POST http://localhost:8000/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "secure123"}'
# Returns: {"api_key": "sk-octopoda-...", "tenant_id": "..."}

# Store a memory
curl -X POST http://localhost:8000/v1/agents/my_agent/remember \
  -H "Authorization: Bearer sk-octopoda-..." \
  -H "Content-Type: application/json" \
  -d '{"key": "task_result", "value": "Pipeline completed successfully"}'

# Semantic search
curl "http://localhost:8000/v1/agents/my_agent/similar?q=did+the+pipeline+finish" \
  -H "Authorization: Bearer sk-octopoda-..."
```

Full Swagger docs at `/docs`.

**Security built in:**
- Per-tenant SQLite databases (complete data isolation)
- API key auth with bcrypt hashing
- Rate limiting per tenant (10,000 req/min free tier)
- Brute-force protection on login/signup
- SSRF protection on webhooks (HTTPS-only, no private IPs)

---

## MCP Server

Give Claude, Cursor, or any MCP-compatible AI persistent memory with zero code.

```bash
pip install octopoda-memory
```

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

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

**13 tools available:** `octopoda_remember`, `octopoda_recall`, `octopoda_recall_similar`, `octopoda_recall_history`, `octopoda_related`, `octopoda_search`, `octopoda_snapshot`, `octopoda_restore`, `octopoda_share`, `octopoda_read_shared`, `octopoda_list_agents`, `octopoda_agent_stats`, `octopoda_log_decision`

---

## Framework Integrations

Drop-in memory for the frameworks you already use.

```python
# LangChain
from synrix_runtime.integrations.langchain_memory import SynrixMemory
memory = SynrixMemory(agent_id="my_chain")

# CrewAI
from synrix_runtime.integrations.crewai_memory import SynrixCrewMemory
crew_memory = SynrixCrewMemory(crew_id="research_crew")

# AutoGen
from synrix_runtime.integrations.autogen_memory import SynrixAutoGenMemory
memory = SynrixAutoGenMemory(group_id="dev_team")

# OpenAI Agents SDK
from synrix_runtime.integrations.openai_agents import SynrixOpenAIMemory
memory = SynrixOpenAIMemory()
```

---

## Dashboard

Real-time monitoring with 8 tabs: agent overview, memory explorer, knowledge graph visualization, performance metrics, audit log, anomaly detection, system health, and settings.

```bash
octopoda  # Opens dashboard at http://localhost:7842
```

Built with Chart.js, D3.js, and SSE for live streaming updates.

---

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `OCTOPODA_LLM_PROVIDER` | `none` | LLM for fact extraction: `openai`, `anthropic`, `ollama`, `none` |
| `OCTOPODA_OPENAI_API_KEY` | | OpenAI API key |
| `OCTOPODA_OPENAI_MODEL` | `gpt-4o-mini` | OpenAI model |
| `OCTOPODA_OPENAI_BASE_URL` | `https://api.openai.com/v1` | Any OpenAI-compatible endpoint |
| `OCTOPODA_ANTHROPIC_API_KEY` | | Anthropic API key |
| `OCTOPODA_ANTHROPIC_MODEL` | `claude-haiku-4-5-20251001` | Anthropic model |
| `OCTOPODA_OLLAMA_URL` | `http://localhost:11434` | Ollama server URL |
| `OCTOPODA_OLLAMA_MODEL` | `llama3.2` | Ollama model |
| `OCTOPODA_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | Embedding model (33MB) |
| `SYNRIX_DATA_DIR` | `~/.synrix/data` | Data directory |
| `SYNRIX_API_PORT` | `8741` | Cloud API port |

---

## Architecture

```
octopoda
  synrix/                  — SDK layer
    sqlite_client.py       — SQLite + WAL mode + vector search + knowledge graph
    embeddings.py          — Local embeddings (bge-small-en-v1.5, 33MB, CPU)
    extractor.py           — NER + relationship extraction (spaCy)
    fact_extractor.py      — Multi-provider LLM fact decomposition
  synrix_runtime/          — Runtime layer
    api/
      runtime.py           — AgentRuntime (core API)
      cloud_server.py      — FastAPI cloud API (multi-tenant, auth, rate limiting)
      mcp_server.py        — MCP server (13 tools, stdio transport)
      auth.py              — API key management, bcrypt, tenant isolation
    core/
      daemon.py            — Background daemon (heartbeat, GC, recovery)
    monitoring/
      metrics.py           — Performance metrics + anomaly detection
      audit.py             — Full audit trail
    integrations/          — LangChain, CrewAI, AutoGen, OpenAI Agents
    dashboard/             — Flask + SSE real-time dashboard
```

**Storage:** SQLite with WAL mode. No external database required. Handles 500+ concurrent users. Each tenant gets a separate database file for complete isolation.

**Embeddings:** `BAAI/bge-small-en-v1.5` — 384 dimensions, 33MB, runs on CPU. Asymmetric retrieval model optimized for query-document matching.

**Fact extraction:** Any LLM decomposes text into semantically tagged facts. Runs in background threads — `remember()` returns instantly, facts are extracted async.

---

## License

MIT — fully open source, use it however you want.

---

Built by [RYJOX Technologies](mailto:ryjoxtechnologies@gmail.com)
