astrocyte 0.14.2

Open-source memory framework for AI agents

Astrocyte

Open-source memory framework for AI agents. Retain, recall, and synthesize — with pluggable backends, built-in governance, and 18 framework integrations.

---

What is Astrocyte?

Astrocyte gives AI agents persistent memory — store what matters, retrieve what's relevant, synthesize answers from accumulated knowledge. It sits between your agents and their storage, providing:

• Three operations: retain(), recall(), reflect() — one API for every agent and every backend
• Pluggable backends: storage providers (pgvector, Pinecone, Qdrant, Neo4j) or engine providers (Mystique, Mem0, Zep, Letta)
• Built-in governance: PII scanning, rate limits, token budgets, circuit breakers, access control, observability
• 18 framework integrations: LangGraph, CrewAI, OpenAI, Claude Agent SDK, Google ADK, AutoGen, and more
• MCP server: Any MCP-capable agent (Claude Code, Cursor, Windsurf) gets memory with zero code

Quick start

pip install astrocyte

from astrocyte import Astrocyte

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

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

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

# Synthesize an answer from memory
result = await brain.reflect("Summarize what we know about Calvin", bank_id="user-123")

Agent framework integrations

Astrocyte works with every major agent framework through thin middleware — one integration per framework, works with every memory backend.

Framework	Module
LangGraph / LangChain	astrocyte.integrations.langgraph
CrewAI	astrocyte.integrations.crewai
OpenAI Agents SDK	astrocyte.integrations.openai_agents
Claude Agent SDK	astrocyte.integrations.claude_agent_sdk
Google ADK	astrocyte.integrations.google_adk
Pydantic AI	astrocyte.integrations.pydantic_ai
AutoGen / AG2	astrocyte.integrations.autogen
Smolagents (HuggingFace)	astrocyte.integrations.smolagents
LlamaIndex	astrocyte.integrations.llamaindex
Semantic Kernel	astrocyte.integrations.semantic_kernel
DSPy	astrocyte.integrations.dspy
CAMEL-AI	astrocyte.integrations.camel_ai
BeeAI (IBM)	astrocyte.integrations.beeai
Strands Agents (AWS)	astrocyte.integrations.strands
LiveKit Agents	astrocyte.integrations.livekit
Haystack (deepset)	astrocyte.integrations.haystack
Microsoft Agent Framework	astrocyte.integrations.microsoft_agent
MCP (Claude Code, Cursor)	astrocyte.mcp

MCP server

Any MCP-capable agent gets memory with zero code integration:

{
  "mcpServers": {
    "memory": {
      "command": "astrocyte-mcp",
      "args": ["--config", "astrocyte.yaml"]
    }
  }
}

Built-in governance

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

• PII barriers — regex, NER, or LLM-based scanning with redact/reject/warn actions
• Rate limits & quotas — token bucket rate limiting and daily quotas per bank
• Circuit breakers — automatic degraded mode when backends go down
• Access control — per-bank read/write/forget/admin permissions
• Observability — OpenTelemetry spans and Prometheus metrics on every operation
• Data governance — classification levels, compliance profiles (GDPR, HIPAA, PDPA)

Multi-bank orchestration

Query across personal, team, and org banks with cascade, parallel, or first-match strategies:

hits = await brain.recall(
    "What are Calvin's preferences and team policies?",
    banks=["personal", "team", "org"],
    strategy="cascade",
)

Memory portability

Export and import memories between providers — no vendor lock-in:

await brain.export_bank("user-123", "./backup.ama.jsonl")
await brain.import_bank("user-123", "./backup.ama.jsonl")

Evaluation

Benchmark memory quality with built-in suites and DeepEval LLM-as-judge:

from astrocyte.eval import MemoryEvaluator

evaluator = MemoryEvaluator(brain)
results = await evaluator.run_suite("basic", bank_id="eval-bank")
print(f"Recall precision: {results.metrics.recall_precision:.2%}")

Benchmarks

Astrocyte includes adapters for two academic memory benchmarks plus built-in eval suites.

Benchmark	What it tests	Dataset
LoCoMo (ECAI 2025)	Long-term conversational memory — single-hop, multi-hop, temporal, open-domain QA	snap-research/locomo
LongMemEval	Long-context memory extraction, reasoning, temporal ordering	xiaowu0162/LongMemEval

Quick start

The PageIndex bench (M9+) requires Postgres + a real LLM provider; secrets are loaded via Doppler (DOPPLER_TOKEN set in your environment or doppler login once locally). The Makefile already runs doppler run -- for every bench target.

# Full LoCoMo run (200 stratified questions by default, ~$1 in API costs)
make bench-locomo

# Quick variant — cap to ~50 questions for fast iteration
make bench-locomo LOCOMO_MAX_Q=5

# LongMemEval (200 samples by default; ~$5 in API costs)
make bench-longmemeval
make bench-longmemeval LME_MAX_SAMPLES=50      # quick

# Parallel run on two Postgres containers (locomo on :5433, lme on :5434)
make bench-parallel

Results land under benchmark-results/pageindex/{locomo,lme}/ and are automatically uploaded to the R2 archive (see make bench-archive-* targets).

Dataset management

Datasets are cloned to datasets/ (gitignored) on first benchmark run. To manage manually:

make fetch-datasets       # Fetch all datasets
make clean-datasets       # Remove downloaded datasets
make clean-results        # Remove benchmark results

See docs/_design/evaluation.md for the full evaluation specification.

Development

From astrocyte-py/ with the dev extra:

uv sync --extra dev
uv run ruff check astrocyte/ tests/
uv run python -m pytest tests/ -x --tb=short

Git hooks (Ruff via pre-commit) — reduces CI lint failures. From the repository root (parent of astrocyte-py/):

uv sync --extra dev --directory astrocyte-py
uv run --project astrocyte-py pre-commit install

Hooks run automatically on git commit; run on all files anytime with:

uv run --project astrocyte-py pre-commit run --all-files

CodeQL is not run in pre-commit (too slow for every commit). Enable Code scanning under the repo’s Settings → Code security so GitHub runs CodeQL on pushes/PRs using the default or advanced setup.

Documentation

astrocyteai.github.io/astrocyte

• Quick Start
• Architecture
• Provider SPI
• Integration guides (one per framework)

License

Apache 2.0 — see LICENSE.