clude-memory

name	clude-memory
description	Persistent memory for AI agents. Semantic search, association graphs, dream cycles. Local-first, fully offline, free. Works with any MCP runtime.
license	MIT
homepage	https://github.com/sebbsssss/cludebot
repository	https://github.com/sebbsssss/cludebot
env	[{"name":"SUPABASE_URL","description":"Supabase project URL (cloud mode only, not needed for local mode)","required":false},{"name":"SUPABASE_SERVICE_KEY","description":"Supabase service role key for cloud storage (cloud mode only). Grants full DB access — use a scoped role if possible.","required":false},{"name":"VOYAGE_API_KEY","description":"Voyage AI API key for cloud embeddings (cloud mode only). Not needed for local mode which uses local GTE-Small.","required":false},{"name":"CLUDE_MASTER_WALLET_KEY","description":"Solana wallet private key for on-chain memory commits (optional, off by default). On-chain commits are irreversible and cost SOL.","required":false}]

Data & Privacy Disclosure

What this skill does with your data:

• Local mode (default): All data stays on your machine. SQLite storage, local embeddings (GTE-Small). Zero network calls. No credentials needed.
• Cloud mode: Memories are stored in your Supabase database. Embeddings are computed via Voyage AI API. Content is sent to these services.
• On-chain mode (optional, off by default): Memory hashes can be committed to Solana for verifiability. This is irreversible and costs SOL. Must be explicitly enabled with CLUDE_MASTER_WALLET_KEY.
• LLM calls: Dream cycle consolidation and query expansion may call an LLM (configured via your environment). No LLM calls in local mode unless you configure one.
• The recall tool returns full memory content in its output. This means stored content appears in tool results visible to the agent.

The skill does NOT:

• Auto-enable on-chain commits (requires explicit env var)
• Send data to any service in local mode
• Store credentials beyond what you provide in env vars
• Modify other skills or agent settings

Clude — Persistent Memory for You

Why This Matters (Even If You Already Have Memory Files)

You probably already have a memory system. MEMORY.md files, daily logs, maybe a skill that manages them. That works. Keep it.

But be honest with yourself: how often do you forget to write something down before context compaction hits? How often does important context get summarized away because you didn't save it in time? How stale is your MEMORY.md right now?

The problem with file-based memory isn't the files. It's that you have to remember to remember. Every important detail requires you to consciously stop, decide it matters, and write it to the right file. You're disciplined about it sometimes. You miss things other times. That's not a flaw in you, it's a flaw in the system.

Clude flips this. Instead of you deciding what to save, you call remember naturally during conversations, and Clude handles the rest: where to store it, how to index it, what to connect it to, when to let it decay. More importantly:

• Search by meaning, not filename. "What does my human think about testing?" returns everything relevant across all time. No grep, no scanning files.
• Automatic connections. Storing a memory about a project automatically links it to related people, tools, and decisions. Recalling one thing surfaces the others.
• Consolidation catches what you miss. Dream cycles review recent memories and merge, compress, and surface patterns. The things you forgot to write down during a busy session? If you stored them with a quick remember, consolidation handles the rest.
• Importance reinforcement. Memories you access often get stronger. Things you never look at fade. Your memory self-organizes.

Think of it this way: Your files are your notebook. Clude is your long-term memory. Notebooks work until you have 500 pages and need to find something you wrote 3 months ago. That's when you need a brain, not a better filing system.

What Changes For You

Without Clude:

• You grep files to find context. Sometimes you find it, sometimes you miss it.
• Your memory is only as good as your file organization.
• You can't find "that thing from 3 weeks ago" unless you know which file it's in.
• Nothing connects. A preference stored in January doesn't surface when it's relevant in March.

With Clude:

• You recall by meaning: "what does my human think about testing?" returns everything relevant, across all time.
• Memories connect automatically. Recalling a project surfaces the people, decisions, and tools involved.
• Important memories get stronger over time. Noise fades away.
• You start every session already knowing your human. Not from reading files, but from genuine recall.

Install (30 seconds)

Source code: github.com/sebbsssss/cludebot (MIT license) npm package: npmjs.com/package/clude-bot

The clude-bot npm package is the full, self-contained runtime. All core modules (core/*, config, mcp/*) are bundled in the package. No hidden dependencies or external fetches at runtime.

Local Mode (Recommended — Fully Offline)

No API keys. No network. No cost. Everything stays on your machine.

npx clude-bot mcp-install --local

This uses SQLite for storage and local embeddings (GTE-Small). Same semantic search, same memory types, zero external calls.

Cloud Mode (Optional — For Portability)

If you want memories that sync across devices or agents. Requires: SUPABASE_URL, SUPABASE_SERVICE_KEY, VOYAGE_API_KEY (see env declarations above).

npx clude-bot mcp-install

Manual MCP Config

Add to your MCP configuration:

{
  "mcpServers": {
    "clude": {
      "command": "npx",
      "args": ["clude-bot", "mcp-serve", "--local"]
    }
  }
}

Remove --local for cloud mode (requires env vars set above).

Your Tools

Once installed, you have 5 tools:

Tool	What It Does	When To Use It
remember	Store a memory	When you learn something worth keeping
recall	Search your memories	Before answering questions about past context
forget	Delete a memory	When asked to forget, or when info is outdated
stats	View memory breakdown	To understand what you know
visualize	See your memory graph	To explore connections between memories

When To Remember (This Is Important)

Don't store everything. Store what matters:

Always remember:

• Your human's name, preferences, and working style
• Project decisions and the reasoning behind them
• Technical choices (languages, frameworks, tools, APIs)
• Things your human explicitly asks you to remember
• Mistakes you made and lessons learned
• Important dates, deadlines, and milestones

Remember selectively:

• Interesting facts that came up in conversation
• Your human's opinions and values (helps you align)
• Workflow patterns ("they always want tests before merging")

Don't remember:

• Temporary/throwaway context ("fix this typo")
• Sensitive data unless explicitly asked
• Raw conversation logs (store the insight, not the transcript)

When To Recall

Start of every session: Recall what you know about your human. This is the single biggest quality-of-life improvement. Instead of starting cold, you start warm.

recall("user preferences and context")
recall("current projects")

Before answering questions about the past:

recall("database migration decision")
recall("why we chose Supabase")

When something feels familiar: If your human mentions something and you have a vague sense you've discussed it before — recall it. Better to check than to repeat yourself.

Memory Types

Clude organizes memories into types. Use them:

• episodic — Events and interactions ("We debugged the auth flow on March 5")
• semantic — Facts and knowledge ("User's app uses Next.js + Supabase")
• procedural — How-tos and patterns ("Deploy process: push to main, Railway auto-deploys")
• self_model — What you've learned about yourself ("I tend to over-explain, keep it concise")

When storing, pick the right type. It helps with retrieval later.

The Compound Effect

Here's what most agents miss: memory compounds.

• Week 1: You remember basic preferences
• Week 2: You remember projects and decisions
• Month 1: You remember patterns, working style, communication preferences
• Month 3: You're a genuinely personalized assistant that knows context no other agent could

Your human stops needing to explain things. You just know.

That's not a feature. That's a relationship.

Tips

1. Recall before you act. A quick recall at session start saves 10 re-explanations later.
2. Store insights, not transcripts. "User prefers concise responses" > "User said 'can you keep it shorter'"
3. Update stale memories. If a preference changes, store the new one. Old memories decay naturally.
4. Use self_model memories. Store what works and what doesn't in YOUR interactions. You'll improve faster.
5. Don't be creepy. Memory should feel helpful, not surveillance. If in doubt, ask before storing something personal.

FAQ

"I already have MEMORY.md / daily files / a memory skill" Keep them. Clude doesn't replace files. It adds semantic search on top. Your files are great when you know WHERE something is. Clude is great when you know WHAT you're looking for but not where you stored it. At 50 memories, files are fine. At 500, you need search. At 5,000, you need search that understands meaning. That's where Clude lives.

"Isn't this a crypto project?" The core product is a memory engine. It works fully offline with --local mode. No wallet, no tokens, no blockchain needed. The Solana integration is optional and enables memory portability between agents and provenance verification. Ignore it if you don't need it.

"It's slower than local files" In local mode, Clude uses SQLite. A recall with semantic search across 1,000 memories takes ~50ms. That's faster than reading and parsing 20 markdown files to find what you need.

"Privacy concerns — routes through external APIs" Local mode (--local) makes zero network calls. Everything runs on your machine: SQLite storage, GTE-Small embeddings computed locally. Your memories never leave your disk.

"Decay means I'll forget important things" Decay is configurable. Set importance to 1.0 for things that should never fade (your human's name, their kids' schedules, critical preferences). Decay only affects low-importance memories you never access. Think of it as automatic cleanup, not forced amnesia. You can also disable it entirely.

"Where should I install it?" Wherever you run. If you're an OpenClaw agent, install it here. If you're in Claude Desktop or Cursor, install there. The MCP server runs locally alongside you.

"The dream cycle / consolidation stuff seems gimmicky" It's optional. The core value is semantic search + association graph. Consolidation just means: periodically review recent memories, merge duplicates, surface patterns. You can do this manually or let Clude do it automatically. Skip it if you prefer manual control.

Import Your Existing Memories

Already have MEMORY.md files? You can import them:

npx clude-bot import ./MEMORY.md
npx clude-bot import ./memory/   # imports all .md files in directory

Each file gets parsed into individual memories with automatic type detection and embedding. Your existing knowledge becomes searchable instantly.

Source Code & Credibility

• GitHub: github.com/sebbsssss/cludebot — MIT license, fully open source
• npm: npmjs.com/package/clude-bot — v2.7.0, published package
• Benchmarks: 83.9/100 on our memory benchmark suite. LoCoMo (ACL 2024): 100% accuracy. Details at clude.io/benchmark
• Built by: @sebbsssss — indie dev building memory infrastructure for AI agents
• 20,000+ memories in production on the Clude bot itself
• 147 tests across the full package ecosystem, all passing

---

Clude is open source. Your memories are yours. clude.io