Astrocyte design documentation
Astrocyte is an open-source memory framework that sits between agents and storage—it provides a stable API for retain/recall/synthesize, pluggable retrieval and memory-engine backends, and a built-in policy layer for governance and observability.
This folder (docs/) is the shared design specification for the Astrocyte framework. The same repository also contains the parallel service implementations: astrocyte-py/ (Python) and astrocyte-rs/ (Rust). Those directories are the Python and Rust Astrocyte services; design documents here apply to both unless stated otherwise.
Scope: The framework is memory + governance + provider SPIs. It is not an LLM gateway and not an agent runtime: it does not define orchestration (graphs, tool loops, checkpoints, scheduling, multi-agent routing). How that split maps to context engineering (what the model sees) vs harness engineering (how the agent loop runs) — and where Astrocyte sits between them — is spelled out in Architecture framework §1 (Context engineering vs harness engineering). Agent cards and agent catalogs are a common way to describe deployable agents; Astrocyte does not host the catalog or run the agent graph, but it is designed so card identity feeds memory through an explicit, repeatable mapping to principal + memory bank (declarative config and thin resolver helpers—see architecture-framework.md §1 and agent-framework-middleware.md). Vendor-specific card fields that are irrelevant to memory stay outside the core contract.
Diagrams: Architecture figures use Mermaid (flowchart, etc.). They render on GitHub, in VS Code with a Mermaid preview, and in most modern Markdown tools.
Implementations (this repository):
| Folder | Role |
|---|---|
astrocyte-py/ | Python Astrocyte service; PyPI package name astrocyte; ecosystem integrations (LangChain, MCP, …). |
astrocyte-services-py/ | Optional REST (astrocyte-rest) and astrocyte-pgvector; not part of the core SPI. Docker: docker-compose.yml; runbook (scripts/runbook-up.sh); Makefile for common Compose commands. Operations, env split (ASTROCYTES_REST_DATABASE_URL vs host migrate DSN), and debugging: astrocyte-services-py/README.md and Production-grade reference server §4. |
astrocyte-rs/ | Rust Astrocyte service; native crate; same framework contract as Python (see implementation-language-strategy.md). |
Source layout: Spec markdown lives in docs/_design/, docs/_plugins/, and docs/_end-user/ (underscore-prefixed authoring folders). Tutorials stay under docs/_tutorials/. scripts/sync-docs.mjs mirrors them into src/content/docs/{design,plugins,end-user,tutorials}/ (gitignored) so published URLs stay /design/…, /plugins/…, etc. pnpm dev and pnpm build run sync-docs first (predev / prebuild); if you edit _design/ / _plugins/ / _end-user/ / _tutorials/ directly, run node scripts/sync-docs.mjs (or restart dev) so the site picks up changes. Cross-references in prose often use backticked filenames like `architecture-framework.md` as stable identifiers.
Authored hubs (non-numbered): Quick Start, 100 Agents in 100 Days.
1. End User Documentation
Section titled “1. End User Documentation”| # | Title | Topic |
|---|---|---|
| 1 | Quick Start | Install core library; Docker Compose + reference REST |
| 2 | Production-grade HTTP service | Production HTTP checklist; astrocyte-rest; Compose; ops §4.5 |
2. Plugin Developer Documentation
Section titled “2. Plugin Developer Documentation”| # | Title | Topic |
|---|---|---|
| 1 | Provider SPI: Retrieval, Memory Engine, LLM, Memory Export Sink, and Outbound Transport | Retrieval, Memory Engine, LLM; memory export sink §5; outbound §6; multimodal §4.11 |
| 2 | Ecosystem, packaging, and open-core model | Packages, entry points (memory_export_sinks, …), open-core |
| 3 | Outbound transport plugins (credential gateways) | Credential gateways, HTTP/TLS proxy plugins |
| 4 | Multimodal LLM SPI and DTOs | Vision/audio in chat — ContentPart, adapters |
| 5 | Agent framework middleware | LangGraph, CrewAI, etc. (memory hooks, not orchestration) |
3. Design Documentation
Section titled “3. Design Documentation”Indexes below use topic bands (sidebar order matches astro.config.mjs).
3.1 Foundations
Section titled “3.1 Foundations”| # | Title | Topic |
|---|---|---|
| 1 | Astrocyte in neuroscience | Biological metaphor and vocabulary |
| 2 | Design principles | Engineering principles mapped from neuroscience |
| 3 | Astrocyte framework architecture | Layers, two-tier providers, SPI overview |
| 4 | Storage and data planes | Hub: retrieval vs export vs in-process bank health |
| 5 | Applied AI fellowship ↔ Astrocyte | Crosswalk: stack planes, memory vs RAG, teaching hooks |
| 6 | Implementation language strategy | Parallel Python + Rust drop-in implementations |
3.2 Trust & safety
Section titled “3.2 Trust & safety”| # | Title | Topic |
|---|---|---|
| 7 | Identity integration and external access policy | IdP integration, optional external PDP / Casbin; §8 — repo placement |
| 8 | Access control | Principals, permissions, banks |
| 9 | Sandbox awareness and memory-API exfiltration | Sandbox context, egress, Backend for Frontend (BFF) |
| 10 | Data governance and privacy | Classification, residency, DLP |
3.3 Runtime memory
Section titled “3.3 Runtime memory”| # | Title | Topic |
|---|---|---|
| 11 | Innovations roadmap | Pipeline roadmap; Astrocyte vs Mystique open-core split |
| 12 | Presentation layer & multimodal services | Video/voice beside the LLM SPI (Tavus-class) |
| 13 | Policy layer | Homeostasis, barriers, pruning, observability |
| 14 | Use-case profiles | YAML profiles for scenarios |
| 15 | Built-in intelligence pipeline | Tier 1 intelligence pipeline |
| 16 | Multi-bank orchestration | Multiple memory banks |
| 17 | MCP server integration | MCP tool integration |
| 18 | Memory Intent Protocol (MIP) | Declarative memory routing — mechanical rules + LLM intent |
3.4 Durability & movement
Section titled “3.4 Durability & movement”| # | Title | Topic |
|---|---|---|
| 19 | Memory portability | AMA export / import between providers |
| 20 | Memory lifecycle management | TTL, compliance, legal hold, audit |
| 21 | Event hooks | Webhooks, callable hooks, export bridge |
| 22 | Memory export sink | Warehouse / lakehouse / Iceberg / Delta / Parquet emit SPI |
3.5 Quality & proof
Section titled “3.5 Quality & proof”| # | Title | Topic |
|---|---|---|
| 23 | Bank health & utilization | In-process bank health, utilization, Prometheus (not warehouse export) |
| 24 | Evaluation and benchmarking | Benchmarks and regression testing |
4. Tutorials & Examples
Section titled “4. Tutorials & Examples”| # | Title | Topic |
|---|---|---|
| 1 | 100 Agents in 100 Days | Series hub: 100 Agents in 100 Days (daily tutorials, planned) |
Add new days as Markdown files under _tutorials/ and link them from the hub (or use a day-NN-*.md convention).
Shorter paths
Section titled “Shorter paths”Numbers below refer to §3 Design bands (single index 1–24) and §2 Plugins (1–5).
- New to the framework: Design 1 → 2 → 3, optional 4 (storage hub), then Plugins 1 or End user 2.
- Implementing a provider: Plugins 1, 2; Design 6 (implementation language strategy).
- Warehouse / lakehouse — agent-time
recall: Tier 1 adapters — Design 3, 4, Plugins 1 §1. - Warehouse / lakehouse — durable export: Design 4, 22 (memory export sink), Plugins 1 §5, 2 §3.5; 21 (event hooks bridge until core loads
memory_export_sinks:). - Security and compliance: Design 13, 8, 20, 10, 9, 7 (policy, access, lifecycle, data governance, sandbox, identity).
- Declarative memory routing: Design 18 (MIP), 17 (MCP server), 13 (policy layer).
- Integrations (network, identity, UI): Plugins 3, Design 7, 12, Plugins 4.
- Production HTTP / Backend for Frontend (BFF) hosting Astrocyte: End user 2; Design 3, 7, 8, 13, 20, 10, 9; Plugins 3.
Building this documentation site
Section titled “Building this documentation site”This docs/ folder is also the Starlight package. From docs/, run pnpm install, then pnpm dev to preview the site or pnpm build to emit dist/. The script scripts/sync-docs.mjs reads specs from docs/_design/, docs/_plugins/, docs/_end-user/, and docs/_tutorials/ and mirrors them into src/content/docs/{design,plugins,end-user,tutorials}/, and writes introduction.md from this README (generated paths are gitignored). Deployment: .github/workflows/docs.yml.