basicmachines-co/basic-memory

AI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN

Basic Memory – Persistent, searchable knowledge for LLMs

What it is – Basic Memory is an open‑source, local‑first knowledge‑base that lets large‑language‑model (LLM) agents read and write the same Markdown files a human edits. The files are plain text, so you keep full ownership, but the tool also provides a semantic‑search index, a tiny knowledge‑graph built from wikilinks, and a set of MCP‑compatible tools that any AI client (Claude, Codex, Cursor, VS Code, ChatGPT, etc.) can call.

Why it matters – Most LLM workflows are ephemeral: the model forgets everything after the conversation ends. Basic Memory bridges that gap by turning the conversation history into structured, searchable notes that survive across sessions, devices, and even cloud‑hosted sync. Because the data lives in ordinary Markdown, you can use any editor (Obsidian, VS Code, Vim…) and you never get locked into a proprietary format.

Core features (as described in the README)

  • Plain‑text, local‑first storage – All notes are ordinary Markdown files on your disk.
  • Two‑way sync – Humans edit files; LLM agents can create, edit, move, or delete them via MCP tools. A sync layer (optional cloud service) keeps multiple devices consistent.
  • Knowledge‑graph via wikilinks – [[link]] syntax creates entities and relations that the model can traverse.
  • Semantic search – Hybrid full‑text + vector retrieval (FastEmbed embeddings) with optional cross‑encoder reranking for higher quality results.
  • MCP‑native tool set – A catalog of commands (write_note, read_note, search_notes, schema_infer, …) each annotated with behavior hints (read‑only, destructive, idempotent, open‑world) so agents can discover capabilities without trial‑and‑error.
  • Cloud option – A hosted version (Basic Memory Cloud) offers web, mobile, and desktop access, automatic backups, and rclone‑based conflict resolution, all for $15 / mo (free trial, OSS discount available).
  • Extensible integrations – Official plugins for Claude Code, Hermes, OpenClaw, and generic “skills” that can be added to any MCP‑compatible agent.
  • Schema utilities – schema_infer, schema_validate, schema_diff let you infer and enforce a structure on your notes.
  • CLI improvements – JSON output, project‑aware commands, and a dashboard for quick status checks.

Getting started (quick paths)

Path Steps Cost
Cloud 1️⃣ Open the web app, 2️⃣ Connect your AI client (Claude, Codex, Cursor, etc.) $15 / mo (7‑day free trial, OSS discount code BMFOSS for 20 % off 3 months)
Local install uv tool install basic-memory --prerelease=allow (or pip install basic-memory) → configure your AI client’s mcpServers entry → run bm commands Free (AGPL‑3.0)

The README also shows how to add the server to specific clients (Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, ChatGPT, Obsidian). Once configured, you can issue prompts like:

Create a note about our project architecture decisions.
Find information about JWT auth in my notes.
What have I been working on this week?

The LLM will write or retrieve the appropriate Markdown files automatically.

Typical use cases

  • RAG for personal knowledge – Store meeting notes, design decisions, code snippets, and let any LLM retrieve them contextually.
  • Team‑wide shared context – With the cloud workspace, all teammates see the same notes; agents can hand‑off tasks between humans and bots.
  • Agent‑driven documentation – LLMs can auto‑generate or update docs (write_note, edit_note) as code changes.
  • Rapid prototyping of AI‑augmented workflows – Plug the MCP tools into custom agents (Hermes, OpenClaw, etc.) without writing a new API layer.
  • Air‑gapped environments – Run the local version on a secure machine; the data never leaves the host.

Installation & runtime details

  • Package manager – Recommended via uv (uv tool install …). The package is also on PyPI (pip install basic-memory).
  • Python version – Requires Python 3.12 or newer.
  • Optional vector store – For large semantic indexes you can install the milvus extra (basic-memory[milvus]).
  • Dependencies – FastMCP 3.0, FastEmbed for embeddings, SQLite (default) or Postgres for vector storage, optional Milvus for larger deployments.
  • Running – basic-memory mcp starts the MCP server; the CLI (bm …) talks to it. The just recipes (just package-check, etc.) verify that all host‑native agent packages build correctly.

Licensing & community

  • License – AGPL‑3.0 (source code freely available, must share modifications under the same license).
  • Open‑source badges – PyPI version badge, test workflow badge, Ruff linting badge, and MCP server/dev badges indicate active CI.
  • Community – The project is listed on the Model Context Protocol (MCP) toplist and has a DeepWiki entry. Testimonials from users (TrainerDay, Caleb Picker Consulting, @groksrc) are included in the README.

Bottom line

Basic Memory provides a pragmatic, file‑based memory layer for LLM agents, turning ordinary Markdown into a searchable, graph‑aware knowledge base that both humans and AI can edit. It can be run entirely locally for free or used as a managed cloud service for a modest subscription, making it suitable for solo developers, research labs, or small teams that want persistent, controllable context for their AI workflows.

Related

  • Project
    doobidoo/mcp-memory-service

    A persistent, shared memory backend for AI agents that provides a knowledge graph and semantic search across sessions and tools via REST API and MCP.

  • Project
    agentic-box/memora

    An MCP memory layer for AI agents that provides persistent, structured storage and semantic retrieval of facts, tasks, and documents via a knowledge graph.

  • Project
    akitaonrails/ai-memory

    ai‑memory is a Rust‑based server that records every observation a coding‑assistant makes (prompts, tool calls, session boundaries) as plain markdown files in a git‑backed wiki. The server can be run locally, in Docker/Podman, or on a homelab box and is designed to be shared across many agents (Claude Code, Codex, Cursor, Gemini CLI, etc.), machines and team members. Hooks posted by agents are consolidated into readable wiki pages at session end; the next session receives a concise handoff so it can continue exactly where the previous one stopped. Storage is human‑readable markdown plus a SQLite index (FTS5, entity and optional vector search). By default it needs no LLM or embedding keys; optional Anthropic/OpenAI integrations add LLM‑generated summaries and semantic search. Multi‑user authentication, audit logs and per‑person attribution are built in. Install via Arch AUR, Docker wrapper, or native binary, start the server, register a client and its hooks, and the system works transparently.

  • Project
    mindmuxai/brain.md

    A persistent, file-based memory layer for coding agents that stores project decisions and constraints as plain Markdown in the repository.

  • Project
    thecodacus/understory

    A self-wiring, plain-markdown memory layer for AI agents that organizes facts into a cross-linked knowledge graph based on the Open Knowledge Format.