Skip to content
Astrocyte — memory framework for AI agents Astrocyte — memory framework for AI agents Astrocyte

Quick Start

Get Astrocyte running — pick the deployment model that fits your stack and follow the commands.

Choose your deployment model

Section titled “Choose your deployment model”

Embed Astrocyte directly in your Python application. No separate server — memory operations run in-process.

Best for: prototyping, single-process agents, notebooks, custom orchestrators.

Terminal window
# Recommended — installs astrocyte + astrocyte-postgres (the default stack).
pip install astrocyte-stack


# Or pick a specific backend:
pip install "astrocyte[postgres]"        # same as above, explicit
pip install "astrocyte[qdrant]"          # Qdrant vector store
pip install "astrocyte[neo4j]"           # Neo4j graph store
pip install "astrocyte[elasticsearch]"   # Elasticsearch document store


# Or in-memory only (tests, evals, embedded use; no DB required):
pip install astrocyte

The default stack (astrocyte-stack) is what the rest of this guide assumes. See ecosystem and packaging for the full matrix of optional dependencies.

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")

The library alone does not start an HTTP server. See the architecture overview and provider SPI for wiring storage backends and LLM providers.

Prerequisites

Section titled “Prerequisites”
  • Python 3.11+ (library and standalone gateway)
  • Docker and Docker Compose (recommended for standalone gateway)
  • Kong, APISIX, or Azure APIM (gateway plugin mode only)

Wire an AI agent

Section titled “Wire an AI agent”

Astrocyte does not run the agent loop (tools, checkpoints, multi-step graphs). Your framework does. Integrations map each framework’s memory hooks to retain / recall / reflect through the same policy layer — see agent framework middleware for the full matrix.

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",
)
vars_for_prompt = await memory.load_memory_variables({})

Per-framework guides live under Integrations (LangGraph, CrewAI, Pydantic AI, OpenAI Agents SDK, Claude Agent SDK, MCP, and 12 more).

Declarative routing with MIP

Section titled “Declarative routing with MIP”

The Memory Intent Protocol (MIP) lets you declare routing rules so Astrocyte decides which bank, tags, and policies to apply — without routing logic in your application code.

# mip.yaml — route student answers to per-student banks
rules:
  - name: student-answer
    match:
      all:
        - content_type: student_answer
        - metadata.student_id: present
    action:
      bank: "student-{metadata.student_id}"
      tags: ["{metadata.topic}"]
brain = Astrocyte.from_config("astrocyte.yaml")


# MIP routes this to bank "student-stu-42" with tag "algebra"
await brain.retain(
    "2x + 3 = 7, so x = 2",
    bank_id="default",  # MIP overrides this
    metadata={"student_id": "stu-42", "topic": "algebra"},
    content_type="student_answer",
)

Mechanical rules resolve deterministically with zero LLM cost. When no rule matches, an optional intent layer can ask an LLM to decide. See the MIP developer guide for the full match DSL, PII lockdown rules, compliance profiles, and testing recipes.

Next steps

Section titled “Next steps”