Enables AI agents to maintain persistent memory across sessions by capturing conversations, extracting durable knowledge, and injecting relevant context, suppor
Enables AI agents to maintain persistent memory across sessions by capturing conversations, extracting durable knowledge, and injecting relevant context, supporting various MCP-compatible platforms.
README
Persistent memory for AI agents. Every conversation remembered. Every decision recalled. Every session informed.
Your AI forgets everything between sessions — who you are, what you decided, what failed, what works. Memory Crystal fixes that.
It captures conversations in real time, extracts durable knowledge, manages raw sensory retention, and injects the right context before every response. One install. No prompting gymnastics. Your AI just knows.
Point at https://api.memorycrystal.ai/mcp with a Bearer token
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.
How it works
You send a message
│
▼
┌─────────────────────────────────────────┐
│ CONTEXT ENGINE │
│ │
│ Semantic search + BM25 across STM/LTM │
│ Knowledge graph boost │
│ Multi-signal reranker │
│ Diversity filter + context budgeting │
│ → Inject top memories into context │
└─────────────────────────────────────────┘
│
▼
AI responds with full context
│
▼
┌─────────────────────────────────────────┐
│ MEMORY EXTRACTION │
│ │
│ Raw message → Short-term memory │
│ LLM extracts facts/decisions → LTM │
│ Graph enrichment links related memories│
└─────────────────────────────────────────┘
Every response is informed by what came before. Every conversation feeds the next one.
Two memory layers
Layer
Stores
Retention
Short-term (STM)
Recent raw messages, verbatim
Rolling window by tier
Long-term (LTM)
Facts, decisions, lessons, people, rules
Permanent, vector-indexed
Sensory raw content
Raw sensory payloads behind memory records
Summarized, tombstoned, or protected by policy
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
Store
Purpose
Example
sensory
Raw signals
"the user sounds frustrated about the deploy"
episodic
Events
"We shipped v2 on March 15"
semantic
Facts
"The API uses Convex for the backend"
procedural
How-to
"Deploy with npm run convex:deploy"
prospective
Plans
"Add billing webhooks next sprint"
Knowledge graph
Memories don't exist in isolation. An async background job connects related memories — decisions link to the lessons that informed them, people link to their projects, rules link to the events that created them.
When the Context Engine searches, graph-connected memories rank higher. Your AI doesn't just remember facts — it understands relationships.
Adaptive recall
Six modes, automatically selected:
Mode
Prioritizes
General
Broad recall across STM + LTM
Decision
Decisions, lessons, and rules before risky changes
Project
Goals, workflows, and implementation context
People
Ownership, collaborators, and relationships
Workflow
Procedures, rules, and how-to memory
Conversation
Recent session context and continuity
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
Background enrichment — embedding and graph backfill run asynchronously
24 memory tools
Every tool works in any MCP host or automatically within OpenClaw hooks.
Tool
What it does
crystal_recall
Semantic search across all long-term memory
crystal_remember
Store a memory — decisions, facts, lessons
crystal_what_do_i_know
Everything known about a topic
crystal_why_did_we
Decision archaeology — why a past choice was made
crystal_preflight
Pre-flight check before risky actions
crystal_search_messages
Hybrid search over verbatim conversation history
crystal_checkpoint
Snapshot memory state at a milestone
crystal_wake
Session startup — briefing and guardrails
crystal_trace
Trace a memory back to its source conversation
crystal_who_owns
Find ownership of a file, module, or area
crystal_explain_connection
Explain relationships between concepts
crystal_dependency_chain
Trace dependency chains between entities
crystal_recent
Recent messages for short-term context
crystal_edit
Update an existing memory
crystal_forget
Archive or delete a memory
crystal_stats
Memory and usage statistics
crystal_set_scope
Override channel scope for the session
crystal_list_knowledge_bases
List available knowledge bases
crystal_query_knowledge_base
Search a knowledge base
crystal_import_knowledge
Import reference chunks into a KB
crystal_ideas
List active Organic ideas and discoveries
crystal_idea_action
Act on Organic ideas
memory_search
Search LTM and return crystal paths
memory_get
Read a full memory by ID or path
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.
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 organic model features.
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 Convex project
CONVEX_DEPLOYMENT=prod:your-project-123 npx convex deploy
# Configure
echo 'CONVEX_URL=https://your-project-123.convex.cloud' > 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
автор: modelcontextprotocol
автор: xuzexin-hz
