Memory for every agent.

Astrocyte is an open-source framework that gives AI agents persistent memory — with pluggable backends, built-in governance, and a pipeline that works out of the box.

Quick Start View on GitHub

Get started in seconds

Pick a deployment model, then wire memory into your agent framework. Optionally add MIP (Memory Intent Protocol) to declare routing rules — Astrocyte decides which bank, tags, and compliance policies to apply, with zero routing code in your app.

Embed Astrocyte directly in your Python app. No separate server — memory operations run in-process. Best for prototyping, single-process agents, notebooks.

pip install astrocyte==0.15.0 astrocyte-postgres==0.15.0

uv pip install astrocyte==0.15.0 astrocyte-postgres==0.15.0

from astrocyte import Astrocyte

brain = Astrocyte.from_config("astrocyte.yaml")

await brain.retain("Calvin prefers dark mode.", bank_id="user-123")
hits = await brain.recall("What theme does Calvin prefer?", bank_id="user-123")

Run Astrocyte as a REST API with Docker Compose. Agents call /v1/retain, /v1/recall, /v1/reflect over HTTP. Best for multi-agent deployments and shared memory services.

Save as docker-compose.yml — no repo clone needed, images are pulled from GHCR:

services:
  postgres:
    image: ghcr.io/astrocyteai/astrocyte/astrocyte-postgres:latest
    environment:
      POSTGRES_USER: astrocyte
      POSTGRES_PASSWORD: astrocyte
      POSTGRES_DB: astrocyte
    ports: ["5433:5432"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U astrocyte"]
      interval: 3s
      retries: 5

  gateway:
    image: ghcr.io/astrocyteai/astrocyte/astrocyte-gateway-py:latest
    environment:
      DATABASE_URL: postgresql://astrocyte:astrocyte@postgres:5432/astrocyte
      ASTROCYTE_VECTOR_STORE: postgres
      ASTROCYTE_GRAPH_STORE: age
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    ports: ["8080:8080"]
    depends_on:
      postgres:
        condition: service_healthy

Start it:

OPENAI_API_KEY=sk-... docker compose up

Exercise the API end-to-end:

# 1. Health check (also confirms the DB is reachable)
curl http://127.0.0.1:8080/health

# 2. Retain a memory
curl -X POST http://127.0.0.1:8080/v1/retain \
  -H "Content-Type: application/json" \
  -d '{"content": "Calvin prefers dark mode.", "bank_id": "user-123"}'

# 3. Recall it
curl -X POST http://127.0.0.1:8080/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "What theme does Calvin prefer?", "bank_id": "user-123"}'

More endpoints — mental models, graph search, governance, portability — in the full quick-start. See Production-grade HTTP service for auth, TLS, and observability.

Add memory to LLM calls routed through an existing API gateway — zero agent code changes. Requires a running standalone gateway that the plugin calls via HTTP.

cp gateway-plugins/kong/handler.lua /path/to/kong/plugins/astrocyte/
cp gateway-plugins/kong/schema.lua  /path/to/kong/plugins/astrocyte/

curl -X POST http://localhost:8001/services/my-llm/plugins \
  -d "name=astrocyte" \
  -d "config.astrocyte_url=http://astrocyte-gateway:8900" \
  -d "config.default_bank_id=shared"

cp gateway-plugins/apisix/astrocyte.lua /path/to/apisix/plugins/

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \
  -H "X-API-KEY: $APISIX_ADMIN_KEY" \
  -d '{"uri":"/v1/chat/completions","plugins":{"astrocyte":{"astrocyte_url":"http://astrocyte-gateway:8900"}}}'

cd gateway-plugins/azure-apim
./deploy.sh   # interactive — Bicep, Terraform, APIOps, or portal

Gateway plugins support recall + retain but not reflect or background tasks. See Gateway edge & API gateways.

MIP (Memory Intent Protocol) lets you declare routing rules in mip.yaml and reference it from astrocyte.yaml with mip_config_path: ./mip.yaml. Astrocyte routes automatically — no routing code in your app.

version: "1.0"
banks:
  - id: "student-{student_id}"
    description: Per-student academic memory
    compliance: pdpa
rules:
  - name: pii-lockdown
    priority: 1
    override: true          # compliance — intent layer cannot override
    match:
      pii_detected: true
    action:
      bank: private-encrypted
      tags: [pii, compliance]
      retain_policy: redact_before_store
  - name: student-answer
    priority: 10
    match:
      all:
        - content_type: student_answer
        - metadata.student_id: present
    action:
      bank: "student-{metadata.student_id}"
      tags: ["{metadata.topic}"]

profile: personal

provider_tier: storage
vector_store: postgres
vector_store_config:
  dsn: postgresql://localhost:5432/memories

llm_provider: openai
llm_provider_config:
  api_key: ${OPENAI_API_KEY}
  model: gpt-4o-mini

# PII detection — country-specific + LLM fallback
compliance_profile: pdpa
barriers:
  pii:
    mode: rules_then_llm
    countries: [SG, IN]

# Point to MIP routing policy
mip_config_path: ./mip.yaml

lifecycle:
  enabled: true
  ttl:
    archive_after_days: 90
    delete_after_days: 365

from astrocyte import Astrocyte

brain = Astrocyte.from_config("astrocyte.yaml")

# MIP routes to bank "student-stu-42" with tag "algebra"
await brain.retain(
    "The quadratic formula solves second degree equations",
    bank_id="default",  # MIP overrides this
    metadata={"student_id": "stu-42", "topic": "algebra"},
    content_type="student_answer",
)

hits = await brain.recall("quadratic formula", bank_id="student-stu-42")

No mip.yaml needed — without mip_config_path, content goes straight to the bank you specify.

astrocyte.yaml
Python

profile: personal

# Tier 1: bring your own database
provider_tier: storage
vector_store: postgres
vector_store_config:
  dsn: postgresql://localhost:5432/memories

# LLM for embedding + reflect
llm_provider: openai
llm_provider_config:
  api_key: ${OPENAI_API_KEY}
  model: gpt-4o-mini

from astrocyte import Astrocyte

brain = Astrocyte.from_config("astrocyte.yaml")

await brain.retain("Calvin prefers dark mode", bank_id="user-123")

hits = await brain.recall("What are Calvin's preferences?", bank_id="user-123")

Add langgraph (or your chain stack) when you compile a graph. Same brain backs every framework adapter — see agent framework middleware.

from astrocyte import Astrocyte
from astrocyte.integrations.langgraph import AstrocyteMemory

brain = Astrocyte.from_config("astrocyte.yaml")
memory = AstrocyteMemory(brain, bank_id="user-123")

await memory.save_context(
    inputs={"question": "Theme preference?"},
    outputs={"answer": "Calvin prefers dark mode."},
    thread_id="thread-abc",
)

prompt_vars = await memory.load_memory_variables({})
# → inject prompt_vars["memory"] into the next model message

Three operations, any backend

Retain, recall, and reflect — with pipelines and policies that stay valid when you swap storage or engines.

Retain

Store memories with automatic chunking, entity extraction, and embedding. PII scanning and content validation happen before anything reaches your backend.

Recall

Multi-strategy retrieval — semantic, graph, keyword, temporal — fused with reciprocal rank fusion and reranked. Token budgets enforced automatically.

Reflect

Synthesize answers from memory. Native engine reflect or automatic fallback via LLM. Disposition-aware personality for support, coding, or research agents.

Harness, memory, context, LLM

Your agent stack runs the loop; Astrocyte is the governed memory boundary before context and completions. What you paste into the next turn is still your context-engineering choice — Astrocyte makes the evidence consistent and auditable. Read the architecture note →

Harness

Orchestration, tools, MCP — when to call memory and how the loop runs.

Astrocyte

Retain, recall, reflect — hybrid retrieval, policies, token budgets on the memory path.

Context

Prompt layout and snippets — your app turns hits into system/user messages for the model.

LLMs

Completions and tool calls — any provider or gateway (OpenAI, Anthropic, LiteLLM, OpenRouter, and similar).

Supports all AI agent frameworks

One memory integration for every framework. Each links to a dedicated guide with install, usage, and API reference.

Pluggable storage and engines

Bring your own database or plug in a full memory engine — Astrocyte keeps governance and observability consistent.

pgvectorElasticsearchPineconeQdrantNeo4jMCPLangGraphLiteLLMOpenRouterPortkeyMem0Zep

Tier 1: Retrieval backends

Ship-first adapters include PostgreSQL (pgvector), Qdrant, Neo4j, and Elasticsearch (BM25 / keyword). The built-in pipeline handles embedding, extraction, fusion, and synthesis on top — plus optional recall_authority for synthesis precedence.

Tier 2: Memory engines

Full-stack engines that own the pipeline. Mystique, Mem0, Zep, Letta, Cognee — Astrocyte adds governance, observability, and portability.

Built-in governance

Neuroscience-inspired policies that protect every operation — regardless of backend.

PII barriers

Regex, NER, or LLM-based scanning with country-specific patterns (SG, IN, UK, EU, AU, CA, JP, CN). Per-type actions, DLP output scanning, and compliance profiles (GDPR, HIPAA, PDPA).

Rate limits & budgets

Token bucket rate limiting, daily quotas, and per-operation token budgets. Prevent runaway agents.

Circuit breakers

Automatic degraded mode when backends go down. Empty recall, error, or cache — with controlled recovery.

Observability

OpenTelemetry spans and Prometheus metrics on every operation. Switch providers without rebuilding dashboards.

Access control

Per-bank read/write/forget/admin permissions. Principals, grants, and audit trails built in.

Data governance

Classification levels, compliance profiles (GDPR, HIPAA, PDPA), data residency, encryption, and DLP.

Agents, frameworks, models

One framework, every agent stack.

MCP Server

Any MCP-capable agent (Claude Code, Cursor, Windsurf) gets memory via astrocyte-mcp. Zero code integration.

Memory Intent Protocol (MIP)

Declarative memory routing — mechanical rules resolve deterministically, LLM judgment only when needed. One mip.yaml governs bank routing, compliance enforcement, and escalation across all agents.

Agent Frameworks

LangGraph, CrewAI, Pydantic AI, OpenAI Agents SDK, AG2 — thin middleware wires Astrocyte into each framework’s memory abstraction.

LLM Providers

Multi-provider gateways (e.g. LiteLLM, Portkey, OpenRouter, Vercel AI Gateway) or direct SDKs — OpenAI, Anthropic, Bedrock, Azure, Vertex, Ollama — or bring your own via the LLM SPI.

Memory Portability

Export and import memories between providers using Astrocyte Memory Archive (AMA), a portable newline-delimited JSON (JSONL) format. No vendor lock-in.

Explore the docs

Quick Start Install, configure, and run your first retain/recall in minutes.

Production-grade HTTP service Operate astrocyte-gateway-py: auth, health, Compose, observability checklist.

Gateway edge & API gateways Kong, APISIX, Azure APIM; CORS, limits, rate limits; benchmark and OpenAPI gates.

Provider SPI Build a storage adapter or engine provider for Astrocyte.

Architecture Two-tier model, layer boundaries, and design principles.

Product roadmap M1–M11 milestones, the v0.9.x pre-GA surface, and the path to v1.0.0 GA.

Memory Intent Protocol Declarative routing — mechanical rules + LLM intent for multi-agent memory.

100 Agents in 100 Days Daily tutorials for building AI agents with persistent memory.