Cursor Memory
Persistent, searchable memory for Cursor AI β You control what your AI remembers.
Ask AI about Cursor Memory
Powered by Claude Β· Grounded in docs
I know everything about Cursor Memory. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
cursor-memory
Persistent, searchable memory for Cursor AI β You control what your AI remembers.
The Problem β’ Quick Demo β’ Installation β’ Commands β’ How It Works β’ Troubleshooting
π€ The Problem
You just spent an hour with Cursor AI figuring out the right architecture. You made decisions, weighed trade-offs, landed on a solution.
Then you open a new chat.
β "What database did we choose last week?"
β "I don't have access to previous conversations."
β "Continue the migration plan from yesterday."
β "Could you provide context about the migration?"
β "Why did we pick EFS over EBS again?"
β "I don't have information about previous decisions."
Every new chat, your AI has amnesia. Every decision you made, every context you built β gone.
The workarounds make it worse:
π Save to a .md file | Now you have 1.000 files. Which one was it again? |
| π Attach files to every chat | Token costs pile up. Most of it isn't even relevant. |
| π Retype context manually | You become the memory for a tool that's supposed to help you think. |
β¨ See It in Action
βΆ Can't see the video? Watch on GitHub
π― Why cursor-memory
You decide what gets saved. Type /memo when something matters β AI creates a structured memo, tags it, and stores it locally. Next time you need it, it's there.
| ποΈ You control what's saved | Nothing gets saved without you triggering /memo. No background processes, no noise. |
| β‘ Context-aware auto-search | AI detects when your question refers to past context and automatically searches your memories β no command needed. /recall is available as a manual fallback. |
| π Finds what you mean, not what you type | Hybrid FTS5 keyword + vector semantic search. Searches by meaning, not just exact words. |
| π Cross-language | Save in any language, search in any language. Multilingual E5 β 100+ languages, fully cross-lingual. |
| π Structured summaries | AI generates organized memos with Decisions β Key Details β Context β Next Steps β not raw text dumps. |
| π Handles long content | Long discussions are automatically split into overlapping chunks β every section is searchable, nothing gets lost. |
| π Global + per-repo scope | Global memories visible everywhere. Repo memories isolated per project β one repo never sees another's context. |
| π§ Choose your model | Small (~50MB), Medium (~115MB), or Large (~270MB) β pick the size that fits your machine. |
| π Fully private, runs offline | No cloud. No API keys. No telemetry. Everything stays on your machine. |
π¦ Installation
Prerequisites
- Node.js β Node 20, 22, or 24 LTS recommended (download)
- Native modules ship prebuilt binaries for these versions, no build tools required.
- C++ compiler (optional) β only needed as a fallback for non-LTS Node versions (Xcode CLI on Mac,
build-essentialon Ubuntu, VS Build Tools on Windows).
β‘ 2-minute setup
# 1. Install globally
npm install -g cursor-memory
# 2. Setup β downloads model, configures Cursor automatically
cursor-memory setup
# 3. Restart Cursor β done π
The CLI handles everything:
- π₯ Downloads the embedding model
- βοΈ Configures MCP server for Cursor
- π Sets up AI behavior rules
π€ Choose your model
| Model | Size | RAM | Best for |
|---|---|---|---|
| Small | ~50MB | ~200MB | Lightweight, fast |
| Medium | ~115MB | ~500MB | Good balance |
| Large β | ~270MB | ~1GB | Best accuracy (recommended) |
All models support 100+ languages and run fully offline after download.
π¬ Commands
In Cursor Chat
Three commands. That's it.
| Command | What it does |
|---|---|
/memo or /memo [text] | πΎ With text β saves directly. Without β AI summarizes the conversation into a structured memo |
/recall [query] | π Searches your memories by keyword + semantic meaning |
/forget [query] | ποΈ Searches β previews matches β confirms before deleting |
AI detects when your question refers to past context and automatically searches your memories β no command needed.
/recallis available as a manual fallback.
π οΈ CLI Commands
cursor-memory setup # First-time setup or switch model
cursor-memory status # Check MCP, rules, model, database health
cursor-memory reset # Clear all data and start fresh
cursor-memory -v # Show version
cursor-memory --help # Show all commands
π¬ How It Works
πΎ Architecture
πΎ Save & Search Flow
π Scope Isolation
π§ͺ Tech Stack
| Component | Technology | Why |
|---|---|---|
| π MCP Server | @modelcontextprotocol/sdk | Standard protocol for AI tool integration |
| ποΈ Database | better-sqlite3 | Zero-config, fast, embedded, WAL mode |
| π Vector search | sqlite-vec | Native C extension, cosine KNN, no external DB |
| π Full-text search | SQLite FTS5 | BM25 ranking, auto-sync via triggers |
| π§ Embeddings | @huggingface/transformers | Local ONNX inference, no API keys |
| π Model | Multilingual E5 (Q8) | 100+ languages, asymmetric search, quantized |
| β¨οΈ CLI | commander | Interactive setup, model management |
| π» Language | TypeScript (ESM) | Type safety, modern module system |
π Troubleshooting
π MCP not connecting after setup
Restart Cursor completely (quit and reopen β not just reload window).
cursor-memory status # check system health
If auto-config failed, manually add MCP server in Cursor:
Cursor β Settings β MCP β Add server, or edit your MCP config file:
{
"mcpServers": {
"cursor-memory": {
"command": "npx",
"args": ["-y", "cursor-memory"]
}
}
}
β οΈ Node.js version mismatch / "unsupported Node.js version"
cursor-memory requires Node 20, 22, or 24 LTS β these are the versions that ship with prebuilt native binaries (better-sqlite3). Other versions may fail to install.
Check your version:
node -v
If you're on a non-LTS version (18, 19, 21, etc.), install an LTS via nvm:
nvm install 22
nvm use 22
npm install -g cursor-memory
cursor-memory setup
If you switched Node versions after installing, just reinstall:
npm install -g cursor-memory
cursor-memory setup
π AI doesn't auto-search memories
Run cursor-memory setup again to reinstall rules.
If that doesn't work, manually add the rule via Cursor β Settings β Rules β create a new User rule and paste the following:
## cursor-memory MCP
### Auto-recall
BEFORE answering, ask yourself: "Does the user expect me to know something from a previous chat?"
If YES β call search_memory from cursor-memory MCP immediately. Do NOT answer first.
If UNSURE β answer normally, do NOT search.
Signs of past context (any language):
- References to previous decisions ("what did we choose", "as we discussed")
- Continuation requests ("continue the plan", "pick up where we left off")
- "We/our" referring to past work, not general questions
- Temporal cues: "last time", "before", "already", "remember", "yesterday"
### Auto-save awareness
After a substantive conversation, assess whether it produced knowledge worth preserving:
SUGGEST SAVING when:
- A decision was reached (chose X over Y, with reasoning)
- A plan, strategy, or approach was agreed upon
- A problem was analyzed and a solution was identified
- A comparison or evaluation was completed with a conclusion
- Important context, constraints, or requirements were established
- Knowledge was shared that would be useful to recall in future sessions
Do NOT suggest when:
- Quick Q&A with a generic/textbook answer
- Still exploring β no conclusion or decision yet
- User already said /memo in this conversation
How to suggest: at the END of your response, briefly ask:
"This seems worth remembering. Want me to /memo this?"
Do NOT auto-save without user confirmation.
### Commands
/memo β save to memory. With content: save directly. Without content: summarize conversation then save.
/recall β search via search_memory
/forget β delete via delete_memory
β Search returns no results
- Try more specific terms
- Similarity threshold is 0.2 β very broad queries may not match
- Consider upgrading to a larger model for better recall accuracy
π οΈ Development
git clone https://github.com/tranhuucanh/cursor-memory.git
cd cursor-memory
npm install
npm run build # build once
npm run dev # watch mode
node dist/cli.js setup
node dist/index.js
π€ Contributing
- π΄ Fork the repository
- πΏ Create feature branch:
git checkout -b feature/your-feature - πΎ Commit:
git commit -m 'feat: your feature' - π Push:
git push origin feature/your-feature - π Open a Pull Request
π License
MIT β see LICENSE.
π Acknowledgments
- Model Context Protocol SDK
- HuggingFace Transformers.js
- sqlite-vec by Alex Garcia
- Multilingual E5 by Microsoft
