Repolode
Submit
basicmachines-co

basicmachines-co/basic-memory

Local-first memory layer that lets AI assistants like Claude and Cursor read and write your notes as plain Markdown files via MCP.

View on GitHubWebsite
Stars
4,509
Forks
352
Open issues
76
Last commit
19 hours ago

What is it?

Basic Memory gives AI assistants persistent memory. Knowledge is stored as Markdown files on your disk, where each note is an entity with observations (facts in bracketed categories) and relations (wikilinks to other notes). Both you and your AI client can read, write and search the same files, and edits made in Obsidian or an editor show up for the assistant as well.

The project exposes its tools over the Model Context Protocol, so it works with Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code and any other MCP-compatible client. It uses a local SQLite index by default, with Postgres as an alternative backend. Search combines full-text and semantic vector ranking, and an optional cross-encoder reranker can refine results.

A hosted cloud version is also offered for cross-device sync and backups, but the local install is AGPL-3.0 licensed and runs without any server.

Key features

  • 01Stores knowledge as plain Markdown files with wikilinks and frontmatter.
  • 02Works with any MCP client, including Claude, Codex, Cursor and VS Code.
  • 03Supports keyword, semantic vector and hybrid search over notes.
  • 04Optional cross-encoder reranking for vector and hybrid results.
  • 05Offers a CLI for project management, health checks, imports and tool access.
  • 06Runs locally on SQLite, with a Postgres backend option.

Use cases

  • Keeping project architecture decisions and context available across AI chat sessions.
  • Building a personal knowledge base that both you and your AI assistant can edit.
  • Importing past conversations from Claude or ChatGPT into searchable notes.
  • Using Obsidian as an editor for notes an AI assistant also maintains.

Quick start

  1. 1

    Install Basic Memory with uv

    uv tool install basic-memory --prerelease=allow
  2. 2

    Add the Basic Memory server to your AI client config (example for Claude Desktop)

  3. 3

    Restart your AI client and start using it

Things to know

  • Local install requires Python managed through uv.
  • Licensed under AGPL-3.0, a copyleft license that requires sharing modified source code when offered as a network service.
  • Depends on a FastMCP pre-release, so the --prerelease=allow flag is required or an older version gets installed.

In collections

MCP servers for Claude CodeClaude Code tools, skills & pluginsMCP serversPrivacy & local-first toolsOpen-source personal AI agentsStatic site generators & documentation tools

Topics

#ai#mcp#markdown#knowledge-management#local-first#llm#personal-agent#obsidian#claude#knowlege-graph

FAQ

What is basic-memory?
Local-first memory layer that lets AI assistants like Claude and Cursor read and write your notes as plain Markdown files via MCP. Basic Memory gives AI assistants persistent memory. Knowledge is stored as Markdown files on your disk, where each note is an entity with observations (facts in bracketed categories) and relations (wikilinks to other notes). Both you and your AI client can read, write and search the same files, and edits made in Obsidian or an editor show up for the assistant as well.
Is basic-memory free to use? What license does it have?
basic-memory is open source under the AGPL-3.0 license. Check the license terms before using it in commercial products.
Is basic-memory still maintained?
Actively maintained. The last commit to basic-memory was on Nov 6, 2026.
What can I use basic-memory for?
Keeping project architecture decisions and context available across AI chat sessions. Building a personal knowledge base that both you and your AI assistant can edit. Importing past conversations from Claude or ChatGPT into searchable notes. Using Obsidian as an editor for notes an AI assistant also maintains.
How do I install basic-memory?
Install Basic Memory with uv: uv tool install basic-memory --prerelease=allow Add the Basic Memory server to your AI client config (example for Claude Desktop) Restart your AI client and start using it
Where can I get basic-memory?
The source code and installation instructions are on GitHub: https://github.com/basicmachines-co/basic-memory

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects