MemoryBuddy 🧠

中文版

Give your AI agents a shared memory that lasts. Deploy once, connect any MCP-compatible AI tool — Hermes, Trae, Cursor, Claude Desktop — they all share the same memory.

🌟 What is this?

Most AI tools suffer from "goldfish memory" — refresh the page, start a new session, switch to another app, and everything's gone. You keep reintroducing yourself, re-explaining your preferences, re-stating context.

MemoryBuddy fixes this with a shared memory layer that any AI tool can read from and write to:

• 🧠 Long-term memory — facts, preferences, decisions persist across sessions
• 🔍 Semantic search — find relevant memories by meaning, not just keywords
• 🤖 Auto fact extraction — LLM automatically distills what's worth remembering
• 📝 Smart summarization — long conversations get compressed, key points retained
• 🗑️ One-click forget — DELETE wipes everything, GDPR compliant
• 🔌 MCP protocol — any MCP-compatible client can connect, zero integration code
• 💸 $0/month — runs entirely on Cloudflare's free tier

💡 What problem does it solve?

😣 Without MemoryBuddy	✅ With MemoryBuddy
Every AI tool starts fresh — you re-explain yourself constantly	All your AI tools share one memory — tell one, they all know
Switching from Hermes to Trae means losing all context	Switch freely — memory lives in the cloud, not in the tool
AI forgets your preferences between sessions	Preferences persist forever, across all sessions and all tools
Long conversations hit context limits	Auto-summarization keeps things compact
Privacy concerns — can't delete what it remembers	One API call wipes everything, fully GDPR compliant

🏗️ Architecture

┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│ Hermes  │   │  Trae   │   │ Cursor  │   │ Claude  │
└────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘
     │ MCP         │ MCP         │ MCP         │ MCP
     ▼             ▼             ▼             ▼
┌──────────────────────────────────────────────────┐
│           MemoryBuddy Worker (Cloudflare)         │
│                                                  │
│   /mcp  → MCP Server (5 tools, Streamable HTTP)  │
│   /chat → HTTP API (SSE streaming + auto-extract)│
│   /memory/:userId → REST API                     │
└──────────┬──────────────────┬────────────────────┘
           │                  │
     ┌─────▼─────┐    ┌──────▼──────┐
     │ D1 (facts)│    │ Vectorize   │
     │ SQLite DB │    │ (embeddings)│
     └───────────┘    └─────────────┘

Three-tier memory:

1. Short-term (Durable Object) — current conversation context
2. Long-term (D1 database) — structured facts: name, preferences, key entities
3. Semantic (Vectorize) — vector embeddings for meaning-based recall

🚀 Quick Start (3 steps, ~5 minutes)

Prerequisites

• Cloudflare account (free is fine)
• Node.js 18+

1. Clone & Install

git clone https://github.com/Trainspotting31/memory-buddy.git
cd memory-buddy
npm install

2. Create Cloudflare Resources

npx wrangler login

# Create D1 database
npx wrangler d1 create memory-buddy-db

# Create Vectorize index
npx wrangler vectorize create memory-buddy-index --dimensions 768 --metric cosine

# Initialize database schema
npx wrangler d1 execute memory-buddy-db --remote --file=schema.sql

Copy the generated database_id into wrangler.toml (rename from wrangler.toml.example).

3. Deploy

npx wrangler deploy

Done! Your memory server is live at https://memory-buddy.<your-subdomain>.workers.dev 🎉

🔌 Connect Your AI Tools

MemoryBuddy speaks MCP (Model Context Protocol). Any MCP-compatible tool can connect — they all share the same memory.

Hermes Agent

hermes mcp add memory-buddy --url https://memory-buddy.<your-subdomain>.workers.dev/mcp

Trae IDE

1. Settings → MCP → Add Manually
2. Type: Streamable HTTP
3. URL: https://memory-buddy.<your-subdomain>.workers.dev/mcp

Or create .trae/mcp.json in your project:

{
  "mcpServers": {
    "memory-buddy": {
      "type": "streamable-http",
      "url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memory-buddy": {
      "url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "memory-buddy": {
      "type": "streamable-http",
      "url": "https://memory-buddy.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Any MCP Client (raw config)

Endpoint: https://memory-buddy.<your-subdomain>.workers.dev/mcp
Transport: Streamable HTTP
Auth: None (or add your own)

🛠️ MCP Tools

Once connected, the AI gets 5 tools:

Tool	What it does	When AI calls it
recall_memory	Load all memory for a user	Start of conversation
search_memory	Semantic search by meaning	"What did I say about X?"
store_memory	Save a new fact	User shares preferences, decisions
forget_memory	Delete all memory	User says "forget everything"
list_memory_users	List all memory spaces	Checking what exists

Shared memory: All tools default to userId: "hermes-shared". Use different userIds to isolate memory per project/persona.

📡 HTTP API (no MCP needed)

POST /chat — Chat with memory

curl -N -X POST https://your-worker.workers.dev/chat \
  -H "Content-Type: application/json" \
  -d '{"userId":"user123","message":"Hi! I'm John and I love espresso."}'

GET /memory/:userId — Get all memory

curl https://your-worker.workers.dev/memory/user123

DELETE /memory/:userId — Wipe memory

curl -X DELETE https://your-worker.workers.dev/memory/user123

GET /health — Health check

curl https://your-worker.workers.dev/health

⚙️ Configuration

Edit wrangler.toml:

[vars]
LLM_MODEL = "@cf/meta/llama-3.2-3b-instruct"  # Default: Workers AI (free)

# Optional: use external LLM instead of Workers AI
LLM_API_KEY = "sk-your-key"
LLM_API_BASE = "https://api.openai.com/v1"
LLM_MODEL = "gpt-4o-mini"

💸 Why Cloudflare Free Tier?

Component	Free Tier	Self-Hosted Equivalent
Compute (Workers)	100K req/day	$5–$50/mo (VPS)
Database (D1)	1GB storage	$10–$100/mo (Postgres)
Vector DB (Vectorize)	256K vectors	$70+/mo (Pinecone)
LLM (Workers AI)	10K neurons/day	$10+/mo (API)
Total	$0	~$100+/mo

📁 Project Structure

memory-buddy/
├── src/
│   ├── index.ts          # Hono router: /mcp + /chat + /memory + /health
│   ├── mcp.ts            # MCP Server factory (5 tools, stateless)
│   ├── agent-do.ts       # Durable Object: chat session + memory orchestration
│   ├── llm.ts            # LLM abstraction (Workers AI / OpenAI-compatible)
│   └── memory/
│       ├── extract.ts    # LLM-powered fact extraction
│       ├── retrieve.ts   # Hybrid retrieval (D1 + Vectorize)
│       └── summarize.ts  # Conversation summarization
├── public/index.html     # Built-in demo chat UI
├── schema.sql            # D1 database schema
├── wrangler.toml.example # Cloudflare config template
└── package.json

🎮 Try the Demo

Open your Worker URL in a browser — you'll see a built-in chat interface.

1. Tell the agent your name and a preference ("I'm Sarah, I'm allergic to peanuts")
2. Refresh the page
3. Ask: "What do you know about me?"

It remembers everything. That's MemoryBuddy.

🗺️ Roadmap

• [x] MCP Server (Streamable HTTP)
• [x] Multi-agent shared memory
• [x] Semantic search
• [x] Auto fact extraction
• [ ] Memory categories & filtering
• [ ] User authentication
• [ ] Batch memory import/export
• [ ] Multi-language support
• [ ] Hermes plugin (auto-inject memory at conversation start)

🤝 Contributing

1. Fork → 2. Branch → 3. Commit → 4. Push → 5. PR

📄 License

MIT — see LICENSE