Basic Memory

Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to enable any compatible LLM to read and write to your local knowledge base.

• Website: http://basicmachines.co
• Documentation: http://memory.basicmachines.co

Pick up your conversation right where you left off

• AI assistants can load context from local files in a new conversation
• Notes are saved locally as Markdown files in real time
• No project knowledge or special prompting required

https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc

Quick Start

You can view shared context via files in ~/basic-memory (default directory location).

Alternative Installation via Smithery

You can use Smithery to automatically configure Basic Memory for Claude Desktop:

This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. The Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.

Glama.ai

Why Basic Memory?

Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation starts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:

• Chat histories capture conversations but aren't structured knowledge
• RAG systems can query documents but don't let LLMs write back
• Vector databases require complex setups and often live in the cloud
• Knowledge graphs typically need specialized tools to maintain

Basic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can read and write to. The key advantages:

• Local-first: All knowledge stays in files you control
• Bi-directional: Both you and the LLM read and write to the same files
• Structured yet simple: Uses familiar Markdown with semantic patterns
• Traversable knowledge graph: LLMs can follow links between topics
• Standard formats: Works with existing editors like Obsidian
• Lightweight infrastructure: Just local files indexed in a local SQLite database

With Basic Memory, you can:

• Have conversations that build on previous knowledge
• Create structured notes during natural conversations
• Have conversations with LLMs that remember what you've discussed before
• Navigate your knowledge graph semantically
• Keep everything local and under your control
• Use familiar tools like Obsidian to view and edit notes
• Build a personal knowledge base that grows over time

How It Works in Practice

Let's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:

1. Start by chatting normally:

... continue conversation.

2. Ask the LLM to help structure this knowledge:

LLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):

The note embeds semantic content and links to other topics via simple Markdown formatting.

3. You see this file on your computer in real time in the current project directory (default ~/$HOME/basic-memory).

• Realtime sync can be enabled via running basic-memory sync --watch

4. In a chat with the LLM, you can reference a topic:

The LLM can now build rich context from the knowledge graph. For example:

Each related document can lead to more context, building a rich semantic understanding of your knowledge base.

This creates a two-way flow where:

• Humans write and edit Markdown files
• LLMs read and write through the MCP protocol
• Sync keeps everything consistent
• All knowledge stays in local files.

Technical Implementation

Under the hood, Basic Memory:

1. Stores everything in Markdown files
2. Uses a SQLite database for searching and indexing
3. Extracts semantic meaning from simple Markdown patterns
   • Files become Entity objects
   • Each Entity can have Observations, or facts associated with it
   • Relations connect entities together to form the knowledge graph
4. Maintains the local knowledge graph derived from the files
5. Provides bidirectional synchronization between files and the knowledge graph
6. Implements the Model Context Protocol (MCP) for AI integration
7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph
8. Uses memory:// URLs to reference entities across tools and conversations

The file format is just Markdown with some simple markup:

Each Markdown file has:

Frontmatter

Observations

Observations are facts about a topic. They can be added by creating a Markdown list with a special format that can reference a category, tags using a "#" character, and an optional context.

Observation Markdown format:

Examples of observations:

Relations

Relations are links to other topics. They define how entities connect in the knowledge graph.

Markdown format:

Examples of relations:

Using with Claude Desktop

Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):

1. Configure Claude Desktop to use Basic Memory:

Edit your MCP configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json for OS X):

If you want to use a specific project (see Multiple Projects), update your Claude Desktop config:

2. Sync your knowledge:

3. In Claude Desktop, the LLM can now use these tools:

5. Example prompts to try:

Futher info

See the Documentation for more info, including:

• Complete User Guide
• CLI tools
• Managing multiple Projects
• Importing data from OpenAI/Claude Projects

License

AGPL-3.0

Contributions are welcome. See the Contributing guide for info about setting up the project locally and submitting PRs.

Star History

Built with ♥️ by Basic Machines