Skip to content
/
Tier A A10 Memory engine

Basic Memory

basic-memory · basicmachines-co/basic-memory · ★ 3.1k · last commit 2026-05-26

Primitive shape 24 total
Commands 3 Skills 1 MCP tools 20
00

Summary

Basic Memory — Summary

Basic Memory is a local-first, plain-Markdown knowledge graph MCP server that lets AI agents and humans read, write, and search the same files. It ships a dedicated CLI (basic-memory / bm) with ~15 subcommands and an MCP server with ~20 tools covering write, edit, read, search, and project-management operations across named projects. Notes use a structured-observation syntax (- [category] text #tag) combined with wikilinks to form a graph; SQLite stores indexes but Markdown files remain the source of truth.

The system supports cross-project namespacing (personal notes, team specs, documentation repos all addressed by project= parameter) and optional cloud sync at $14.25/mo that replicates the same Markdown to Postgres+S3. It integrates with every major MCP client including Claude Code, Codex, Cursor, VS Code, and ChatGPT Custom GPTs. A React-based tool UI ships alongside the server for local visualization.

Compared to the seeds, Basic Memory is closest to ccmemory (MCP-anchored memory layer) but uses flat Markdown + SQLite rather than Neo4j; differs from agent-os (markdown scaffold) because it provides active MCP tools that write notes rather than passive template files; differs from taskmaster-ai (task decomposition JSON) by being a general knowledge graph with no task-management primitives. The cross-device cloud sync option and freemium pricing model are unique in this batch.

01

Overview

Basic Memory — Overview

Origin

BasicMachines Co. — AGPL-3.0 open source, with a commercial cloud tier. Active since at least early 2025. Python 3.12+ codebase using FastMCP, SQLAlchemy (SQLite), Alembic, and a fastapi-based sync layer. Cloud hosted on WorkOS AuthKit + Neon Postgres + Tigris S3.

Philosophy

The README opens:

"Your AI never forgets again. Pick up right where you left off — in Claude, Codex, Cursor, ChatGPT, or anything that speaks MCP. Your knowledge lives as Markdown files that both you and your AI can read, write, and search."

Core tenets from NOTE-FORMAT.md and README:

  • Files are the source of truth — changes to .md files automatically update the knowledge graph in the database.
  • Two-way — both AI and humans write to the same files; sync keeps them in step.
  • A real knowledge graph — observations and wikilinks compound into context.
  • Semantic search — find notes by meaning, not just keywords.
  • Progressive tool discovery — every MCP tool is tagged with behavior hints (read-only, destructive, idempotent) so agents pick the right tool without trial and error.

Design Choices

  • AGPL-3.0 license: forcing cloud competitors to share source if they run Basic Memory as a service.
  • Observation syntax: - [category] content text #tag1 #tag2 (context) — structured metadata that survives plain-text editing.
  • Relations via wikilinks: - depends_on [[Entity]] creates typed graph edges stored in SQLite alongside the plain-text file.
  • Project namespacing: all tools accept a project= parameter so a single server can host personal notes, team specs, and multiple codebases side by side.
  • Cloud optional, not required: OSS users can use git or Syncthing for sync; the cloud plan is a convenience layer on top of the same format.
02

Architecture

Basic Memory — Architecture

Distribution

  • PyPI package: uv tool install basic-memory
  • Docker: docker-compose.yml and docker-compose-postgres.yml included
  • Cloud: Hosted at basicmemory.com (same OSS engine + sync)

Install Methods

uv tool install basic-memory       # local OSS (recommended)
uvx basic-memory mcp               # run without installing
docker compose up -d               # Docker mode
/plugin marketplace add ...        # Claude Code plugin (not published yet as plugin)

CLI Binaries

Two aliases registered in pyproject.toml:

  • basic-memory — full name
  • bm — short alias

Subcommands: cloud, db, doctor, import-chatgpt, import-claude-conversations, import-claude-projects, import-memory-json, mcp, orphans, project, schema, status, tool, update

Directory Structure

src/basic_memory/
├── cli/           # CLI commands (main.py + commands/)
├── mcp/           # MCP server (FastMCP)
│   ├── tools/     # ~20 tool modules
│   ├── resources/ # MCP resources
│   └── prompts/   # MCP prompt templates
├── models/        # SQLAlchemy models
├── repository/    # DB access layer
├── indexing/      # File watchers + indexers
├── markdown/      # Note parser (observations, relations, frontmatter)
├── importers/     # ChatGPT/Claude conversation importers
└── api/           # FastAPI sync API (cloud mode)
ui/
└── tool-ui-react/ # React dashboard (Tailwind)

State Files

  • ~/basic-memory/ — default notes directory (configurable)
  • ~/.config/basic-memory/config.json or similar — config
  • SQLite database (path configurable, default inside data dir)
  • .claude/settings.json — hooks config (enableAllProjectMcpServers: true)

Required Runtime

  • Python 3.12+
  • uv (package manager)
  • SQLite (bundled)
  • Optional: Docker for database-only mode

Target AI Tools

Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code, ChatGPT (Custom GPTs via HTTPS), Obsidian (reads same Markdown), and any MCP client.

03

Components

Basic Memory — Components

MCP Tools (~20)

From src/basic_memory/mcp/tools/:

Tool Purpose
write_note Create a markdown note with observations and relations
edit_note Incremental update to an existing note
read_note Retrieve a note by permalink or title
search_notes Semantic or text search across notes
list_directory List notes in a directory/project
delete_note Delete a note and clean up references
move_note Move note to new path; updates all links
recent_activity Notes modified in a time window
canvas unknown (likely visual graph operation)
build_context Assemble a context bundle for a task
view_note Read with relation traversal
read_content Read raw file content
workspaces List available projects/workspaces
project_management Create/list/delete projects
search (alias) Text search
cloud_info Cloud sync status
release_notes What changed in latest version
chatgpt_tools ChatGPT-specific search/fetch endpoints
ui_sdk React UI interaction helpers

CLI Commands (15)

cloud, db, doctor, import-chatgpt, import-claude-conversations, import-claude-projects, import-memory-json, mcp, orphans, project, schema, status, tool, update

Slash Commands (3 in .claude/commands/)

  • release — manage release notes
  • spec.md — manage specs stored in Basic Memory "specs" project
  • test-live.md — integration testing commands

Skills (1 in .claude/skills/)

  • instrumentation — (exact content not retrieved; likely guides Claude to use Basic Memory MCP tools)

Scripts (count: ~5 import scripts)

  • import-chatgpt, import-claude-conversations, import-claude-projects, import-memory-json — CLI batch importers; manual invocation

Hooks

None defined in .claude/settings.json (only permissions + env vars; hooks array absent).

Templates

  • NOTE-FORMAT.md — the canonical note format specification (published in repo root for documentation)

UI

  • ui/tool-ui-react/ — React + Tailwind tool UI for browsing/searching notes locally; served via MCP UI SDK
05

Prompts

Basic Memory — Prompts

Prompt File 1: .claude/commands/spec.md

Technique: Tool-driven step-by-step prompt with conditional branching by argument.

---
allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note
argument-hint: [create|status|show|review] [spec-name]
description: Manage specifications in our development process
---

## Context

Specifications are managed in the Basic Memory "specs" project. All specs live in a centralized location accessible across all repositories via MCP tools.

See SPEC-1 and SPEC-2 in the "specs" project for the full specification-driven development process.

### If command is "create":
1. Get next SPEC number by searching existing specs in "specs" project
2. Create new spec using template from SPEC-2
3. Use mcp__basic-memory__write_note with project="specs"
4. Include standard sections: Why, What, How, How to Evaluate

### If command is "review":
1. Read the specified spec and its "How to Evaluate" section
2. Review current implementation against success criteria with careful evaluation of:
   - **Functional completeness** - All specified features working
   - **Test coverage analysis** - Actual test files and coverage percentage
   - Count existing test files vs required components/APIs/composables
3. Provide honest, accurate assessment - do not overstate completeness
4. Document findings and update spec with review results using mcp__basic-memory__edit_note
5. If gaps found, clearly identify what still needs to be implemented/tested

Technique used: Conditional imperative prompt (argument dispatches to different sub-flows); explicit tool restriction via allowed-tools frontmatter; anti-sycophancy instruction ("do not overstate completeness").

Prompt File 2: NOTE-FORMAT.md (documentation, also serves as an agent-readable prompt)

Technique: Declarative format specification that agents internalize as writing instructions.

Key excerpt:

## Observations
An observation is a categorized fact about the entity. Written as a Markdown list item.
Syntax: `- [category] content text #tag1 #tag2 (context)`

Examples:
- [design] Files are the source of truth #architecture (All state comes from files)
- [tech] Using SQLite for storage #implementation
- [note] Need to add error handling #todo

## Relations
- Explicit: `- relation_type [[Entity]] (optional context)`
- `- depends_on [[Content Parser]] (Need for semantic extraction)`
- `- "based on" [[Design Notes]]`

Technique used: Schema-as-prompt — the format doc is written for both human editors and LLM tool callers, making the note format self-documenting and guiding agent behavior without an explicit system prompt.

MCP Tool Description (from write_note source)

The tool docstring is injected into the MCP protocol and serves as a runtime prompt:

Creates a markdown note with semantic observations and relations.
If the note already exists, returns an error by default. Pass overwrite=True
to replace the existing note. For incremental updates, use edit_note instead.

Technique: Constraint injection via MCP tool descriptions to prevent agent mistakes (duplicate writes, wrong tool choice).

09

Uniqueness

Basic Memory — Uniqueness

Differs From Seeds

Closest seed: ccmemory — both are MCP-anchored memory layers for Claude Code that persist facts across sessions. The critical delta: ccmemory uses Neo4j + Ollama-powered graph embeddings with automatic detection (Stop hook triggers LLM-based extraction after every response); Basic Memory uses SQLite + Markdown files with explicit agent-driven writes (no auto-capture hook). ccmemory's graph has rich typed relationships (CONTINUES, SUPERSEDES, CONFLICTS_WITH) maintained by an LLM; Basic Memory's graph is formed by the agent explicitly writing wikilinks. A second difference: Basic Memory is bidirectionally human-readable (open any .md in Obsidian or VSCode); ccmemory's primary interface is the Neo4j query layer. Basic Memory also offers a cloud sync tier and freemium pricing; ccmemory requires self-hosted Docker. Against taskmaster-ai: taskmaster manages task decomposition in JSON; Basic Memory manages knowledge in Markdown with no task-management primitives.

Positioning

"The knowledge management layer for AI-assisted development — plain Markdown files that outlive any tool, any model, any session." The AGPL license and cloud tier position it as a freemium product. OSS users get the full local engine; teams paying $14.25/mo get cross-device sync, mobile access, and managed backups.

Observable Failure Modes

  1. No automatic capture — if the agent forgets to call write_note, the knowledge is lost at session end.
  2. No context injection hook — agent must proactively call recent_activity or search_notes at session start; if it doesn't, it starts cold.
  3. SQLite scalability — large note repositories (10k+ notes) may have performance issues with the vector search implementation.
  4. Wikilink drift — renaming notes requires manual reference updates (the move_note tool handles this, but the agent must call it explicitly).
  5. AGPL license — commercial users building products on top must open-source their modifications.
04

Workflow

Basic Memory — Workflow

Phases

Phase What Happens Artifact
Install uv tool install basic-memory, configure MCP in client ~/.config/basic-memory/, notes dir
Onboard AI agent uses write_note to record first observations .md files in notes dir
Active Use Agent reads, writes, searches notes during coding sessions Growing knowledge graph
Search Agent calls search_notes or build_context to retrieve relevant facts Context injected into conversation
Review Human reviews notes in editor or React UI; edits are automatically re-indexed Updated SQLite + Markdown
Cross-session handoff Next session starts; agent calls recent_activity or build_context to reload Context without re-reading all files

Approval Gates

None — the framework is entirely tool-driven with no mandatory human approval checkpoints. The spec slash command does include a "review spec" flow, but it is advisory.

Spec Format

Markdown with YAML frontmatter + observations syntax:

---
title: My Decision
type: decision
tags: [auth, database]
---
## Observations
- [decision] Use Postgres for concurrent writes #database
## Relations
- replaces [[Earlier Decision]]

Spec Storage

Per-project folder in ~/basic-memory/<project>/. Notes addressed by project= param in all MCP tools.

Delta vs Whole File

edit_note supports incremental edits (delta); write_note replaces the file (whole-file with overwrite=True). Default is fail-on-duplicate.

06

Memory Context

Basic Memory — Memory & Context

Memory Model

file-based + sqlite — Markdown files are the canonical store; SQLite holds derived indexes (entities, observations, relations, search vectors). Writes go to both simultaneously.

Persistence Scope

project — each named project has its own directory of .md files. Cross-project queries require explicit project= parameter. Optional global via cloud sync across devices.

Knowledge Graph Structure

Notes form a graph via:

  • Observations: typed, tagged facts inside notes (- [category] text #tag)
  • Relations: typed directed edges between notes (- relation_type [[Note Title]])
  • Frontmatter: entity metadata (type, tags, permalink, custom fields)
  • Wikilinks: inline [[Title]] creates automatic links_to relation

Relation types observed in code: depends_on, relates_to, requires, contrasts_with, based_on, implements, in_response_to, supersedes, links_to (implicit)

Context Compaction Strategy

Basic Memory does not explicitly hook into Claude Code's PreCompact event. Instead:

  • build_context tool assembles a compact context bundle on demand
  • recent_activity fetches only recently modified notes (time window)
  • Notes are retrieved by semantic search (only relevant subset, not full graph)
  • The agent is expected to explicitly call search/read tools rather than having the full graph pushed to context

Cross-Session Handoffs

Yes — the entire purpose is cross-session persistence:

  • Agent calls recent_activity or search_notes at session start to reload context
  • No automatic SessionStart hook; agent must proactively retrieve (no push-injection)
  • build_context can produce a structured summary for a task

State Files

  • ~/basic-memory/<project>/*.md — source of truth notes
  • SQLite database (location configurable; default ~/basic-memory/.db/)
  • ~/.config/basic-memory/config.json — server config
  • Cloud: Neon Postgres + Tigris S3 (cloud-only)

Search Mechanism

hybrid — full-text search + semantic (vector) search:

  • SQLite FTS5 for full-text
  • Vector embeddings for semantic search (embedding model not specified in README, likely local)
  • build_context uses hybrid scoring for context assembly

Notable: No Automatic Capture

Unlike ccmemory (Stop hook auto-detects and records), Basic Memory requires the AI agent to explicitly call write_note or edit_note to record information. There is no background capture pipeline. This is a philosophical choice: the agent decides what is worth recording.

07

Orchestration

Basic Memory — Orchestration

Multi-Agent

No native multi-agent orchestration. Multiple agents can share the same notes directory (they write to the same Markdown files + SQLite), making Basic Memory a shared memory substrate for ad-hoc multi-agent setups, but no coordination protocol ships with the framework.

Orchestration Pattern

none — single agent writing/reading notes; no spawn, no delegation.

Isolation Mechanism

none — edits go directly to files on disk. Different projects are isolated by directory + project= parameter.

Execution Mode

interactive-loop — agent calls MCP tools on demand during a Claude Code session; no daemon or background process beyond the MCP server itself.

Multi-Model

No — Basic Memory is model-agnostic (any MCP client works) but ships no model routing configuration.

Context Compaction Handling

no — no explicit PreCompact hook. Agent must proactively use build_context or recent_activity to manage context.

Crash Recovery

no — no crash recovery protocol. Notes written before a crash are persisted in files; the agent restarts from scratch on next session.

Prompt Chaining

no — no prompt chaining pattern. Each MCP tool call is independent.

Auto Validators

none — no auto-validators. The only quality gate is the review subcommand in the spec slash command, which is human-invoked.

08

Ui Cli Surface

Basic Memory — UI & CLI Surface

CLI Binary

  • Name: basic-memory (alias: bm)
  • Type: Own runtime (Python FastAPI / Typer), not a thin wrapper around Claude CLI
  • Subcommands (15): cloud, db, doctor, import-chatgpt, import-claude-conversations, import-claude-projects, import-memory-json, mcp, orphans, project, schema, status, tool, update

Local UI

  • Type: React web dashboard (ui/tool-ui-react/)
  • Stack: React + Tailwind CSS (build.mjs build script)
  • Port: unknown (served via MCP UI SDK tool; port not specified in public source)
  • Features: Note browsing, search, visual graph (likely); served alongside the MCP server

Cloud Web App

  • URL: basicmemory.com
  • Features: Cross-device sync, mobile access, snapshots, backups, one-click connect for AI clients, rclone-powered sync to local Markdown

IDE Integration

Via MCP protocol (stdio or HTTPS). No dedicated VS Code extension. Works natively with VS Code's built-in MCP support, Cursor, Zed, etc.

Observability

  • bm status — show notes count, project health
  • bm doctor — diagnose connectivity and config issues
  • bm db — database operations
  • Cloud dashboard shows sync status, note counts, recent changes

Transport

Supports both stdio (local) and HTTPS (cloud). The cloud mode exposes an HTTPS MCP endpoint that any MCP client can use without installing Python.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k
A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Claude-Supermemory ★ 2.6k
A10 Memory engine

Gives Claude Code team-level persistent memory via a cloud API, sharing project knowledge across developers and sessions without…