Clude Memory

SKILL.md

---
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
---

# 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)

### Local Mode (Recommended — Fully Offline)
No API keys. No network. No cost. Everything stays on your machine.

```bash
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. **This is faster than file-based memory for retrieval once you have 50+ memories.**

### Cloud Mode (Optional — For Portability)
If you want memories that sync across devices or agents:

```bash
npx clude-bot mcp-install
```

### Manual MCP Config
Add to your MCP configuration:

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

Remove `--local` for cloud mode.

## 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:

```bash
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](https://github.com/sebbsssss/cludebot) — MIT license, fully open source
- **npm:** [npmjs.com/package/clude-bot](https://www.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](https://clude.io/benchmark)
- **Built by:** [@sebbsssss](https://x.com/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](https://clude.io)*