mnemo — Cloud-Persistent Memory for AI Agents \U0001F9E0
Your agents are stateless. Your memory shouldn't be.
Every AI agent session starts from zero. Context is lost, decisions are forgotten, and your agents keep rediscovering what they already knew. mnemo externalizes agent memory into TiDB Cloud Serverless — so agents stay disposable, but memory persists forever.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude Code │ │ OpenCode │ │ OpenClaw │
│ Plugin │ │ Plugin │ │ Plugin │
└──────┬───────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└────────────────────┼────────────────────┘
│
┌───────┴────────┐
│ mnemo-server │ ← optional (team mode)
└───────┬────────┘
│
┌───────┴────────┐
│ TiDB Cloud │ ← zero-ops, free tier
│ Serverless │
│ │
│ • VECTOR type │
│ • EMBED_TEXT │
│ • HTTP API │
└────────────────┘
What Problem Does This Solve?
| Pain Point | Without mnemo | With mnemo |
|---|---|---|
| Session amnesia | Agent forgets everything on restart | Memory persists in the cloud |
| Machine-locked | Memory in local files, lost on device switch | Same memory from any machine |
| Agent silos | Claude can't see what OpenCode learned | All agents share one memory pool |
| Team isolation | Teammate's agent starts from scratch | Shared spaces with per-agent tokens |
| No semantic search | Grep through flat files | Hybrid vector + keyword search |
| Concurrent conflicts | Last write silently overwrites | CRDT vector clocks detect & resolve |
Why TiDB Cloud Serverless?
mnemo chose TiDB Cloud Serverless because it uniquely combines everything agent memory needs — in one service, at zero cost:
- Native
VECTORtype — Semantic search in the same table as your metadata. No separate vector database. EMBED_TEXT()auto-embedding — TiDB generates embeddings server-side (e.g.tidbcloud_free/amazon/titan-embed-text-v2). No OpenAI API key required for semantic search.- HTTP Data API — Agents talk to TiDB via
fetch/curl. No database drivers, no connection pools. - Free tier — 25 GiB storage, 250M Request Units/month. More than enough for individual use.
- MySQL compatible — Migrate to self-hosted TiDB or MySQL anytime.
One database gives you relational storage + vector search + auto-embedding + HTTP access. No glue code. No infra.
Hybrid Search: Vector + Keyword
Embedding configured?
┌─────────┴─────────┐
Yes No
│ │
Hybrid search Keyword only
(vector + keyword) (LIKE '%q%')
│ │
┌─────────┴─────────┐ │
Vector results Keyword │
(ANN cosine) results │
└─────────┬─────────┘ │
Merge & rank Direct results
Three embedding options — pick one or none:
- TiDB auto-embedding —
EMBED_TEXT()generates vectors server-side. Zero config. Free. - OpenAI / compatible API — Set
MNEMO_EMBED_API_KEY. Works with Ollama too. - No embedding — Keyword search works immediately. Add vectors later, no migration needed.
Multi-Agent Conflict Resolution (CRDT)
When multiple agents write to the same memory, mnemo uses vector clocks — no coordination required:
Agent A: clock {A:3, B:1} Agent B: clock {A:2, B:2}
\ /
└──── Server compares ─────────┘
│
Neither dominates →
Concurrent conflict!
│
Deterministic tie-break
│
Winner saved, clocks merged: {A:3, B:2}
| Scenario | Result |
|---|---|
| A's clock dominates B's | A wins — B's write is stale |
| B's clock dominates A's | B wins — A's write is outdated |
| Concurrent (neither dominates) | Deterministic tie-break — no data loss |
| No clock sent (legacy client) | LWW fast path — backward compatible |
Deletes are soft (tombstone + clock increment) — no ghost resurrection from agents that missed the delete.
Install for OpenClaw
npm install mnemo-openclaw
Add to openclaw.json:
{
"plugins": {
"slots": { "memory": "mnemo" },
"entries": {
"mnemo": {
"enabled": true,
"config": {
"host": "<your-tidb-host>",
"username": "<your-tidb-user>",
"password": "<your-tidb-pass>"
}
}
}
}
}
Get a free cluster in 30 seconds at tidbcloud.com.
Optional — enable auto-embedding (no API key needed):
{
"config": {
"host": "...",
"username": "...",
"password": "...",
"autoEmbedModel": "tidbcloud_free/amazon/titan-embed-text-v2",
"autoEmbedDims": 1024
}
}
Also Works With
| Platform | Install |
|---|---|
| Claude Code | /plugin marketplace add qiffang/mnemos → /plugin install mnemo-memory@mnemos |
| OpenCode | "plugin": ["mnemo-opencode"] in opencode.json |
| Any HTTP client | REST API or TiDB HTTP Data API directly |
5 Memory Tools
| Tool | What it does |
|---|---|
memory_store | Store a memory (upsert by key, with optional CRDT clock) |
memory_search | Hybrid vector + keyword search across all memories |
memory_get | Retrieve a single memory by ID |
memory_update | Update an existing memory |
memory_delete | Soft delete with tombstone (CRDT-aware) |
Two Modes, One Plugin
| Direct Mode | Server Mode | |
|---|---|---|
| For | Individual developers | Teams with multiple agents |
| Backend | Plugin → TiDB Serverless | Plugin → mnemo-server → TiDB |
| Deploy | Nothing — free tier | Self-host Go binary |
| Features | Hybrid search, auto-embedding | + Space isolation, per-agent tokens, CRDT |
Mode is inferred from config. Start personal, scale to team — no code change.
Links
- GitHub: github.com/qiffang/mnemos
- Design Doc: docs/DESIGN.md
- CRDT Proposal: crdt-memory-proposal.md
- TiDB Cloud Serverless: tidbcloud.com (free tier)
Built for agents that need to remember. Powered by TiDB Cloud Serverless.