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

Quick Start

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

Fastest path: memory for your coding agent

Section titled “Fastest path: memory for your coding agent”

Give Claude Code, Codex CLI, Cursor, Gemini CLI, Windsurf, or Copilot CLI persistent memory in two commands — no database or server, and no new API key (fact extraction uses your Claude Code login, or OPENAI_API_KEY if Claude Code isn’t installed):

Terminal window
uv tool install 'astrocyte[local]'
astrocyte setup

astrocyte setup keeps memories in one local SQLite file, extracts facts with the claude CLI when it is on your PATH (otherwise OPENAI_API_KEY), embeds with a local model, proves the memory server starts, and then registers it with every agent it finds — verifying each registration took effect. astrocyte doctor checks the whole chain end to end; astrocyte doctor --fix repairs it after an upgrade or a moved install.

In Claude Code, Codex and Antigravity, setup also turns on automatic memory for interactive sessions (headless claude -p / codex exec / agy -p runs — scripts, benchmarks — are left alone): each finished turn is saved to the project’s local memory, and genuinely relevant memories are added to new prompts — so the agent knows what was decided last week without being asked to look. A new session opens with where the previous one in that project left off (its last few exchanges, whichever agent it was in). Conversations are stored only on your machine. Pause with ASTROCYTE_HOOKS=off; turn off with astrocyte setup --no-hooks. Codex runs new hooks only once you trust them: run /hooks in Codex after setup.

Windows: the memory tools (MCP) work natively, and so do the pieces of automatic memory (the hooks, which run the same under cmd, PowerShell and Git Bash, and the background process), each tested on Windows in CI. They have not yet been checked against a real agent session on a Windows machine, so WSL remains the recommended way to get automatic memory there for now. astrocyte doctor runs every installed hook through each shell and says if one doesn’t work.

File recall (opt-in, Claude Code): astrocyte setup --claude --file-recall also adds, after the agent reads or edits a file, the memories of earlier turns that touched that file (captured turns record the files they read or edited; Codex turns record only the files they edited, since Codex reads files through shell commands). Each file is answered once per session. It runs a hook on every file read, so it is off unless you turn it on; --no-file-recall turns it off again.

Setup remembers what you switch off: after astrocyte uninstall --claude or astrocyte setup --no-hooks, a later astrocyte setup (after an upgrade, say) leaves it off. Name the agent to turn it back on: astrocyte setup --claude.

See what your agents remember about the project you’re in with astrocyte memory; astrocyte memory search "…" shows what a prompt would recall, and astrocyte memory forget <id> erases a memory from disk (--all --yes for the whole project).

Memory starts empty. Seed it with what your project already tells agents: astrocyte memory import CLAUDE.md AGENTS.md docs/ (setup suggests the files it finds). Each file becomes one memory per section, and re-importing a file syncs it. Move a project’s memory between machines with astrocyte memory export project.ama.jsonl and import on the other.

Share a project’s memory with your team through an Astrocyte gateway the team runs (token mode; an admin creates each person a token, see authentication setup):

Terminal window
astrocyte team join https://memory.example.com --token …   # in the project; previews, then asks
astrocyte team sync                                         # push what's new, pull teammates' memories
astrocyte team status                                       # last sync, what's waiting, token check
astrocyte team leave                                        # stop; erases teammates' memories here

What an agent saved and what you imported are shared; captured conversation stays on your machine unless you join with --share-captured (run team join again to change it; it previews first), and a memory tagged private never leaves it. For one memory, astrocyte memory share <id> sends it anyway (a captured turn goes with all its chunks), and astrocyte memory unshare <id> keeps it here: one already on the gateway is taken off it, so teammates’ copies go at their next sync, while yours stays. astrocyte doctor checks each shared project’s token, gateway and last sync. Teammates’ memories are copied into your local store under the same ids, so recall stays local and works offline, and they are labelled with who saved them: - [2026-10-02] (alice) Deploys go out on Tuesdays. “Where you left off” only ever shows your own sessions. While an agent is open, the background process syncs every joined project every five minutes (ASTROCYTE_TEAM_SYNC_SECONDS); astrocyte team sync does it now. Forgetting a shared memory asks for the scope: astrocyte memory forget <id> --team erases it for everyone (it needs the forget permission on the gateway; each teammate’s copy goes at their next sync), --local on this machine only. The token goes to the OS keychain when the keyring package is installed, else to team.json beside your config (readable only by you).

The rest of this page covers embedding Astrocyte in your own application or running it as a shared service.

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)

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.

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": "Alice 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”