Memory Crystal MCP Server

Your AI forgets everything between sessions — who you are, what you decided, what failed, what works. Memory Crystal fixes that.

It captures each completed conversation once, distills durable knowledge only in bounded session-boundary or indexed nightly batches, and recalls the right context when an agent needs it. The turn write performs no inference. Capture stays automatic; recall defaults to deliberate tool calls so idle sessions cost nothing.

curl -fsSL https://memorycrystal.ai/crystal | bash

Works with everything

Install Memory Crystal on any MCP-compatible AI tool in one command:

The universal installer supports cloud, local, and self-hosted backends. It can register MCP clients, configure OpenClaw, install Codex/Claude hook assets, and stage a Dockerized local Convex backend for offline or self-hosted work.

Related MCP server: mcp-memory

How it works

  You send a message
       │
       ▼
┌─────────────────────────────────────────┐
│           CONTEXT ENGINE                │
│                                         │
│  Vector search across durable LTM       │
│  Lexical fallback over recent messages │
│  Deterministic bounded ranking          │
│  Scope filtering + context budgeting    │
│  → Inject top memories into context     │
└─────────────────────────────────────────┘
       │
       ▼
  AI responds with full context
       │
       ▼
┌─────────────────────────────────────────┐
│         MEMORY EXTRACTION               │
│                                         │
│  Completed turn → STM (idempotent)      │
│  Bounded extraction → durable LTM       │
│  One authoritative LTM vector index     │
└─────────────────────────────────────────┘

Every response is informed by what came before. Every conversation feeds the next one.

Two memory layers

STM gives recent continuity. LTM gives permanent knowledge. Sensory retention lets Memory Crystal keep durable recall value without keeping every raw payload forever.

Five memory stores

Adaptive recall

Six modes, automatically selected:

The Context Engine picks the right mode. You don't configure anything.

Knowledge bases

First-class immutable reference collections for docs, policies, runbooks, and imported source material. They sit alongside conversational memory so your agent can keep learned context and stable reference data separate.

• Immutable — imported chunks stay stable, not rewritten by conversation

• Scoped — tenant and scope filters keep KBs private to the right workspace

• Bulk import — standard import or high-volume bulk-insert without blocking on embedding

• Explicit retrieval — queried only when the agent selects the named KB

• Bounded enrichment — embeddings are generated through guarded import/backfill jobs

Memory tools

Every tool works in any MCP host or automatically within OpenClaw hooks.

Short-term message tools (crystal_search_messages, crystal_recent, recall message matches, and wake/session summaries derived from recent messages) redact likely secrets before returning tool output. A turn becomes searchable after capture finishes at turn completion; active same-turn tool calls should not expect the current prompt or response to appear yet.

HTTP API

All core operations available over authenticated HTTP:

POST /api/mcp/capture              Create a memory
POST /api/mcp/recall               Hybrid recall over all memory
POST /api/mcp/search-messages      Search short-term history

GET  /api/knowledge-bases          List knowledge bases
POST /api/knowledge-bases          Create a knowledge base
POST /api/knowledge-bases/:id/import       Import chunks
POST /api/knowledge-bases/:id/bulk-insert  High-volume migration
POST /api/knowledge-bases/:id/query        Query a knowledge base

All endpoints require Authorization: Bearer <api-key>. Per-key rate limiting enforced.

Architecture

memorycrystal/
├── plugin/                 OpenClaw plugin — hooks into conversation lifecycle
├── plugins/shared/         Shared hook script for Claude Code, Codex, Factory
├── mcp-server/             MCP server — stdio/HTTP compatibility layer
├── packages/mcp-server/    Streamable HTTP MCP variant
├── convex/                 Backend — schema, capture, recall, vectors, retention
│   └── crystal/            All Memory Crystal Convex functions
├── apps/
│   ├── web/                Next.js 15 dashboard (Tailwind 4, Convex Auth)
│   └── docs/               Mintlify documentation site
├── scripts/                Install, bootstrap, doctor, enable/disable
└── assets/                 Logos and brand assets

Local development

Contributors can run an opt-in Dockerized Convex backend and dashboard locally, then seed fixture data without touching the managed production deployment:

npm run convex:local:up
npm run convex:local:seed
npm run convex:local:doctor

Provider keys are intentionally split: MEMORY_CRYSTAL_API_KEY is client bearer auth, GEMINI_API_KEY powers Gemini embeddings, and optional OPENROUTER_API_KEY powers durable memory extraction.

The local stack uses http://127.0.0.1:3210 for Convex RPC, http://127.0.0.1:3211 for HTTP actions, and http://127.0.0.1:6791 for the dashboard. See the Local-First Setup guide for end-user setup, local endpoints, backup and rollback behavior, and troubleshooting.

Self-hosted

Run everything on your own infrastructure:

git clone https://github.com/memorycrystal/memorycrystal.git
cd memorycrystal && npm install

# Deploy to your own self-hosted Convex backend
# Production Memory Crystal uses Railway self-hosted at https://convex.memorycrystal.ai
npm run convex:deploy

# Configure
echo 'CONVEX_URL=https://your-backend-url.example.com' > mcp-server/.env
echo 'GEMINI_API_KEY=your-key' >> mcp-server/.env

# Enable and verify
npm run crystal:enable
npm run crystal:doctor

For install-script OpenClaw installs, verify the loaded plugin directly:

openclaw plugins info crystal-memory
openclaw crystal_status

Full guide: docs.memorycrystal.ai/configuration/self-hosting

Security

• Multi-tenant isolation — owner checks on every retrieval, database-level separation

• Per-peer / channel isolation — on multi-client accounts, memories and knowledge-base chunks are scoped by peer channel and fail closed for broad/absent scopes; recall, wake, and KB queries never surface one client's data in another's session

• API keys — SHA-256 hashed at rest, plaintext never stored

• Content scanner — blocks prompt injection, encoded payloads, credential patterns

• Prompt injection mitigation — recalled memories injected as informational context only

• Rate limiting — per-key enforcement on all endpoints

• Audit logging — all actions logged to crystalAuditLog

• Device flow auth — RFC 8628-style for CLI key provisioning

• Local mode — SQLite fallback, data never leaves your machine

Pricing

Self-hosting is always free. Paid plans are for the managed cloud at memorycrystal.ai.

Contributing

Memory Crystal is MIT open source. PRs welcome.

git clone https://github.com/memorycrystal/memorycrystal.git
cd memorycrystal && npm install && npm run dev

Star History