Memory System

This is the feature that makes Moltbot feel less like a chatbot and more like an actual assistant.

Regular AI chats reset every session. You close the tab, it forgets everything. Moltbot doesn't do that. It remembers your preferences, your projects, your coffee order. Across sessions, across days, across channels.

And the best part? It's all just files. You can read them, edit them, delete them. No proprietary database. No cloud sync. Just Markdown files on your machine.

The Files

Moltbot's memory lives in ~/.moltbot/. Here's what matters:

~/.moltbot/
├── USER.md              # Who you are, your preferences
├── SOUL.md              # The bot's personality and instructions
└── memory/              # Everything else it remembers
    ├── preferences.md
    ├── contacts.md
    ├── projects/
    │   ├── project-a.md
    │   └── project-b.md
    └── daily/
        ├── 2026-01-27.md
        └── ...

USER.md

This is the bot's understanding of you. Your name, your preferences, your habits. Things like "prefers dark mode" or "works on a TypeScript project called Acme" or "allergic to peanuts."

You can edit this file directly. Open it up, add stuff, remove stuff. The bot reads it at the start of every conversation.

SOUL.md

This is the bot's personality. Its instructions, its tone, its boundaries. Think of it as the system prompt, but one you fully control.

Want the bot to be more formal? Edit SOUL.md. Want it to always respond in haiku? (Please don't, but you could.) Edit SOUL.md.

memory/ Directory

This is where the bot stores everything else. Notes from conversations, project details, people you've mentioned, things you've asked it to remember.

The bot organizes these files on its own. It creates subdirectories, names files, structures content. You can reorganize things if you want — the bot will adapt.

Teaching It to Remember

Just tell it.

Remember: I take my coffee black, no sugar

Remember: My GitHub username is johndoe and I work at Acme Corp

Remember: I'm working on a project called Phoenix, it's a React app with a Go backend

The bot writes this info to the appropriate memory file. Next time you chat, it knows.

You can also be less explicit. If you mention something enough times in conversation, the bot picks up on it. But being direct is faster and more reliable.

Retrieving Memories

Ask.

What do you know about me?

What do you remember about the Phoenix project?

Do you know my coffee preference?

The bot searches its memory files and tells you what it's got.

Forgetting Things

Forget my coffee preference

Delete everything you know about Project Phoenix

The bot will remove the relevant entries from its memory files. Or you can just open the files and delete the lines yourself. Same result.

Memory Flush on Compaction

Here's something to know about. When a conversation gets long, Moltbot compacts it — summarizes older messages to stay within the context window. During this compaction, it also flushes important information to memory files.

This means the bot might "remember" something you said 200 messages ago, even though that message is no longer in the active conversation. It wrote it down before compacting.

Pretty clever. But it also means things you say in passing might end up in memory. If that bothers you, check your memory files periodically and clean out stuff you don't want stored.

Vector Search

When the memory directory gets large, keyword matching isn't enough. Moltbot supports vector search to find semantically relevant memories.

How it works: the bot converts your memories into vector embeddings, stores them, and when you ask a question, it finds the memories that are most semantically similar — not just keyword matches.

Providers

Moltbot auto-selects the best available provider:

1. Local — runs embeddings on your machine. No API calls, no cost, private. Slower on older hardware.
2. OpenAI — uses OpenAI's embedding API. Fast, accurate. Costs a tiny amount per query.
3. Gemini — uses Google's embedding API. Similar to OpenAI.

You don't need to configure this. Moltbot picks whatever's available. If you have an OpenAI key set, it'll use that. If not, it falls back to local.

sqlite-vec Acceleration

For large memory stores, Moltbot uses sqlite-vec to speed up vector searches. It's a SQLite extension that does vector similarity search really efficiently.

This installs automatically when needed. If you're on a system where it can't install (some minimal Docker images), vector search still works — just slower.

You probably won't notice the difference until you have hundreds of memory entries. But it's nice to know it scales.

Manual Editing

Honestly love this feature. Everything is just Markdown.

Open ~/.moltbot/memory/ in your text editor, VS Code, whatever. Read through what the bot has stored. Fix things that are wrong. Add things it missed. Delete things you don't want it to know.

The bot re-reads memory files every conversation. Your edits take effect immediately.

Some things you might want to do manually:

• Reorganize: Move files into subdirectories that make sense to you
• Consolidate: Merge scattered notes about the same topic
• Curate: Remove outdated or irrelevant memories
• Bulk import: Paste in a bunch of info about a new project you're starting

The bot doesn't care about the exact file structure. It searches everything in the memory/ directory recursively.

Tips

Keep it lean. More memory = more tokens per conversation = higher costs. If you've got 500 memory entries about a project you finished two years ago, maybe archive those.

Be specific. "Remember I like pizza" is fine. "Remember I like Neapolitan-style pizza with fresh mozzarella, preferably from the place on 5th street" is better. The bot remembers exactly what you tell it.

Don't store secrets. Passwords, API keys, private keys — keep these out of memory files. They're stored as plaintext on disk. Anyone with access to your machine can read them. And if you're using vector search with a cloud provider, your memories get sent to that provider for embedding.

Back up your memory. ~/.moltbot/ is just a directory. Back it up however you back up everything else. Time Machine, rsync, git (just make sure the repo is private).

What's Next

• Security — understand how memory files are stored and who can access them
• Proactive Messages — the bot can use memories for context in scheduled messages
• MCP Tools — give the bot tools that work with its memory