The ephemeral nature of LLM conversations has long been a bottleneck for practical workflow integration. Enter mcp-notes-server, a new TypeScript implementation of the Model Context Protocol that provides Claude with persistent, local memory. Developed by Saurabh Pathak, this tool allows users to save, search, and manage notes across sessions without relying on external cloud services or complex database setups. Everything resides in a single JSON file on your local disk, ensuring data sovereignty and zero network latency for the assistant's memory retrieval.

Architecture and Implementation Details

The server operates as a child process, communicating with MCP clients like Claude Desktop or Claude Code via stdio and JSON-RPC. Pathak’s implementation exposes seven distinct tools—add_note, get_note, list_notes, search_notes, update_note, delete_note, and export_notes—alongside two resources and a review_notes prompt. Each tool is strictly validated using Zod schemas, ensuring that malformed input results in clear errors rather than silent failures or corrupted data. This strict typing is crucial for maintaining stability when the LLM autonomously selects and executes tools.

Security and Concurrency Handling

Pathak prioritized data integrity and security, explicitly avoiding shell execution, SQL queries, and network calls. The file path is controlled by the operator via the NOTES_FILE environment variable, preventing path traversal attacks from tool inputs. To handle concurrent access, the server employs a robust locking mechanism: writers acquire a lock, write to a temporary file, and then atomically rename it over the main notes.json. A 30-second timeout on lock files prevents deadlocks from crashed processes, while a stress test involving four separate OS processes adding 60 total notes validates that no data is lost during simultaneous writes.

The Reality of Search and Future Roadmap

While the persistence layer is robust, the search functionality remains deliberately simple. The current version uses keyword scoring—weighting matches in titles, tags, and body text—rather than semantic embeddings. Pathak explicitly notes this limitation in the README, stating that embeddings are on the roadmap but not yet implemented. This transparency is a welcome change from the usual hype cycles, acknowledging that while the tool solves the memory persistence problem, it does not yet offer the sophisticated semantic recall found in larger vector database integrations.

Key Takeaways

  • Local-first design eliminates cloud costs and privacy concerns for AI memory.
  • Atomic file writes and locking mechanisms ensure data integrity during concurrent access.
  • Current search is keyword-based; semantic embeddings are planned but not shipped.
  • Strict Zod schema validation prevents LLM-induced data corruption.

The Bottom Line

mcp-notes-server is a pragmatic, no-nonsense solution to the stateless nature of LLMs, proving that you don't need a vector database to give Claude a useful memory. It’s a solid foundation for developers who value control and simplicity over premature optimization.

Technical Notes for Developers

Developers can integrate the server with a single command: claude mcp add notes -- npx -y mcp-notes-server. The package is available on npm and supports Node 18, 20, and 22. Pathak’s experience highlights a critical MCP development lesson: stdout is reserved exclusively for the JSON-RPC protocol channel. Any stray console.log statements can break the server’s communication, so all logging must be directed to stderr. End-to-end testing over stdio with the MCP SDK client proved more effective than unit tests for catching these protocol-level issues.