Basic Memory: Linked Markdown Notes for AI Assistants
Basic Memory is a local-first knowledge system whose Markdown files can be read, written, and searched by both people and AI assistants. It helps carry useful information between conversations: project decisions, research notes, meeting summaries, or explanations you want to revisit. A later session must still retrieve the relevant notes; persistence alone does not put them into the model's context.
Files, observations, and relations
Basic Memory represents each note as an entity. An observation is a categorized statement within a note; a relation links it to another note. Together these form a knowledge graph: connected notes that can be explored beyond a single keyword match. The official knowledge-format guide describes the Markdown syntax.
For example, a project note could contain:
# Backtest scope
## Observations
- [decision] Keep the analysis in a command-line script.
- [constraint] Use test data; do not modify production accounts.
- [completion] Finish when the fee-allocation tests pass.
## Relations
- relates_to [[Production isolation]]
This is an illustrative record, not a built-in policy. The linked title refers to another note in the example knowledge base. For a real decision, include who approved it, when it applied, and a link to its source. Distinguish accepted decisions from proposals so a later reader can tell what actually changed.
Connect a project
After following the official installation and client instructions, register a directory for local notes. Replace ./notes with your intended directory and research with a project name of your choice:
basic-memory project add research ./notes --local
basic-memory project list --local
The local project is indexed when it is added. An MCP-compatible client can then use tools such as write_note, read_note, edit_note, and search_notes; build_context follows connections through memory:// URLs. These are tool names, not shell commands. See Model Context Protocol (MCP) for how clients call tools.
A useful interaction is to ask the assistant to find the backtest-scope note in the selected project, read it, and explain which decisions still apply to the current request. Search supports keywords and semantic retrieval; availability and behavior depend on the configured search setup. The official repository lists the tool interface.
Memory is not a permission system
Basic Memory supports two-way editing. It does not inherently limit a project to one note, forbid startup retrieval, or reserve all writes for humans. A team can choose to require approval before changing decision notes, but that rule must be enforced through its client, permissions, and working practices.
An old note may be mistaken or superseded. If it conflicts with the current request or applicable rules, establish which decision is current instead of silently treating the stored text as a higher-priority instruction. Retrieved content can also contain untrusted instructions; storing it in a knowledge graph does not make it safe to follow.
Local Markdown storage does not itself provide cross-device synchronization, backup, or private AI processing. Those depend on the chosen deployment and client. Basic Memory offers optional cloud hosting and synchronization; a connected remote AI service may receive the notes you send it even when the files live locally.
When to use another tool
Use QMD when you primarily want to search a Markdown collection. Use zvec-grep to locate code or document sections in a workspace. Agent Memory and Retrieval connects these choices to source checking and task context. The Python distribution is available on PyPI.