Grain Studios: Coquina
Self-Healing Memory Platform for AI Agents (formerly Cortex)
- Role
- Architect & Developer
- Platform
- Python, PostgreSQL 16, MCP, Apple Silicon
- Industry
- AI Infrastructure
- Focus
- Agent Memory
By the Numbers
Project Overview
Named for the shell-rock I grew up on in St. Augustine Beach — thousands of small fragments bonded into stone that's stronger than any single piece. This is built the same way.
Memories go in raw and organize themselves: auto-embedded, auto-linked by cosine similarity, auto-clustered by project. No curation, no tagging, no manual upkeep.
Dual-path search runs Postgres full-text and ChromaDB vectors in parallel, then merges and ranks them with a recency bonus — exact keywords and fuzzy concepts both land. A-MAC admission control scores every write on five signals before it's allowed in. When relevance drops, a LangGraph loop rewrites the query and tries again.
Four self-evolution subsystems keep it honest: embedding-drift detection, forgetting metrics, two-stage diffusion retrieval, and graph-diffusion consensus. Coquina watches its own health and sharpens over time.
It runs native on Apple M4 Silicon with ChromaDB embedded in-process — no Docker, no zombie containers. Three-tier self-healing covers process, application, and infrastructure. Kill it and it's back in five seconds.
This is the shared memory layer behind every AI agent interaction I run, in production: sub-4ms full-text, 2ms unified search, all on local hardware.
Key Features
- →Three-Tier Self-Healing — Process: LaunchAgent with KeepAlive, self-heal daemon monitors every 60s. Application: embedded ChromaDB eliminates zombie containers by architecture, Redis write buffer replays failed writes on recovery. Infrastructure: automated daily backups, Time Machine hourly snapshots.
- →Dual-Path Search — Every query hits both Postgres full-text search AND ChromaDB semantic vectors. Results merged and ranked with recency bonus. Exact keywords and conceptual similarity both work.
- →A-MAC Admission Control — Quality gate on every write. Scores incoming memories on novelty, specificity, and project relevance. LLM-based scoring via local qwen3.5:9b. Eliminated 288+ duplicate memories/day from health checks.
- →Auto-Linking Relationship Graph — Cosine similarity on every write discovers and connects related memories with typed edges (similar_to, superseded_by, contradicts, supports, depends_on).
- →Adaptive Retrieval (Agentic RAG) — LangGraph-powered query reformulation. Grades retrieved memories, retries with rephrased queries if relevance is low. Agents don't need perfect keywords.
- →Embedded ChromaDB — PersistentClient mode, no separate server process. If Coquina is up, vectors are up. The zombie container problem is eliminated by architecture, not monitoring.
- →Code Intelligence — tree-sitter AST parsing for Python and JS/TS/TSX: function signatures, class hierarchies, import graphs, call sites indexed into searchable memory.
- →Self-Evolution — Four autonomous subsystems that let Coquina monitor and improve itself. Embedding drift detection catches model integrity issues via canary comparisons. Forgetting metrics flag stale memories for review through decay scoring. Two-stage diffusion retrieval expands semantic search iteratively for hard queries. Graph diffusion refines relationship edge weights through consensus scoring.
- →Memory Tiers — Facts, decisions, learnings, preferences, procedural (workflows with success tracking), episodic (session-scoped, auto-expires), and code intelligence.
- →MCP + OAuth 2.1 — Model Context Protocol for native agent integration. Full RBAC, API key management, audit logging. Live dashboard at coquina.studio.
Technical Approach
Local-first, zero cloud, reliability over everything. ChromaDB runs embedded inside the Coquina process, so there's no separate server to crash or orphan. A-MAC gates writes at the door — five scoring signals decide what's worth keeping. The auto-linker builds the relationship graph on every write with typed edges, no human in the loop.
When a query comes back weak, adaptive retrieval reformulates it instead of returning garbage. Three-tier self-healing absorbs process crashes, application degradation, and infrastructure failures without me intervening; a Redis write buffer replays anything that was in flight during a restart.
The MCP interface makes Coquina read as native memory to any agent — no special prompting, no glue code. I built the thing I kept wishing existed.
Outcome
Coquina runs 24/7 on Apple M4 Silicon as the shared memory layer for every agent I operate. The migration off Docker-on-Intel to native-on-M4 doubled query speed and ended the zombie-container problem by architecture, not monitoring.
Kill the process — five seconds and it's back. Every write is quality-gated, every query hits both search paths, every relationship is found automatically.
It changed how I work. Context carries forward, decisions persist, agents build on what came before instead of starting cold. I stopped repeating myself.