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

Memory for your coding agent

Two commands give Claude Code, Codex, Cursor, Gemini CLI, Windsurf and Copilot CLI persistent memory — no database or server; it uses your Claude Code login (or OPENAI_API_KEY) for fact extraction and a local embedding model:

uv tool install 'astrocyte[local]'
astrocyte setup

setup stores memories in one local SQLite file, embeds them with a local model, and wires the MCP server into every agent it finds. In Claude Code, Codex and Antigravity it also turns on automatic memory (Copilot CLI recalls what the others saved): each finished turn is saved to that project's memory, and relevant memories are added to new prompts. Credentials are redacted before anything is stored.

astrocyte doctor          # check everything end to end (--fix repairs it)
astrocyte memory          # what is remembered about the project you're in
astrocyte memory import CLAUDE.md AGENTS.md docs/   # start with what the project already says
astrocyte memory forget <id>

Quick start (library)

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.

MCP server

Any MCP-capable agent gets memory with zero code integration. astrocyte setup registers it for you; to wire one by hand:

{
  "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.

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.