octopoda 2.0.4

Persistent Memory Kernel for AI Agents — crash recovery, shared memory, audit trail, real-time dashboard

Octopoda

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

---

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

pip install octopoda-memory

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.

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

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+.

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:

# 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.

pip install octopoda-memory[nlp]  # Adds spaCy

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.

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.

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.

# 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.

octopoda --api-port 8000

# Sign up
curl -X POST http://localhost:8000/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "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.

pip install octopoda-memory

Add to your Claude Desktop config (claude_desktop_config.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.

# 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.

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