basic-memory: a persistent two-way memory system for AI agents using structured Markdown and MCP

What it solves

Basic Memory provides a persistent, structured memory system for AI agents and humans. It solves the problem of ephemeral LLM conversations where knowledge is lost after a session ends, and overcomes the limits of traditional RAG (which is read-only) by allowing both AI and humans to read and write to a shared, local-first knowledge base.

How it works

The system uses plain Markdown files as the primary source of truth. These files are organized as a knowledge graph of "Entities" containing "Observations" (facts) and "Relations" (links to other notes).

AI agents interact with this memory via the Model Context Protocol (MCP), allowing them to search, create, and edit notes in real-time. Humans can edit these same files using any Markdown editor (like Obsidian). A local SQLite index and semantic vector search (using FastEmbed) enable the AI to find notes by meaning rather than just keywords.

Who it’s for

• AI Power Users: People using Claude, Cursor, or ChatGPT who want their AI to remember project details, learnings, and preferences across sessions.
• Coded-focused users: Developers using IDEs like VS Code or Cursor who want a persistent log of architecture decisions and ProTips.
• Knowledge Workers: Users of Obsidian or other Markdown-based note-taking apps who want an AI assistant to manage and expand their knowledge graph.

Highlights

• Two-way Sync: Both humans and AI can read and write to the same Markdown files.
• MCP-native: Integrates directly with major AI clients like Claude Desktop, Claude Code, Cursor, and VS Code.
• Local-first: Data is stored as plain text on the user's disk, ensuring no vendor lock-in.
• Semantic Search: Combines full-text and vector ranking to find notes by meaning.
• Knowledge Graph: Uses wikilinks and structured relations to allow AI to traverse and build context.
• Progressive Tool Discovery: Tools are tagged with behavior hints (e.g., read-only, destructive) to help agents pick the right tool efficiently.