---
title: "What is Basic Memory"
description: "An overview of what Basic Memory is and how it works."
canonical_url: "https://docs.basicmemory.com/start-here/what-is-basic-memory"
---
# What is Basic Memory

> An overview of what Basic Memory is and how it works.

Basic Memory is real memory for your AI — a knowledge base you own. It stores notes as plain Markdown files, so your work stays readable, portable, and searchable.

Instead of losing valuable insights in conversation history, you build a persistent knowledge base that every AI tool you use can read, write, and enhance — Claude, ChatGPT, Codex, OpenClaw, Hermes, and all your team's agents, working from one shared memory.

<docs-video alt="What Basic Memory is, in one minute" poster="/videos/posters/hero.png" src="https://docs.basicmemory.com/videos/hero.mp4">



</docs-video>

## Why Basic Memory?

**The problem:** AI conversations are ephemeral. You have a great discussion, make important decisions, learn something new - and then it's gone, buried in chat history.

**The solution:** Basic Memory gives your AI assistant a persistent memory. Knowledge captured in one conversation is available in all future conversations. Your AI can reference past discussions, decisions, and context.

**Key benefits:**

- **Persistent context** - Knowledge survives across conversations
- **You own your data** - Plain Markdown files you control
- **Structured knowledge** - Observations and relations create a semantic graph
- **Works with any AI** - Claude, ChatGPT, and other MCP-compatible assistants
- **One memory for all your agents** - every tool reads the same knowledge base; with [Teams](https://docs.basicmemory.com/teams/about), so does your whole team

---

## What it does

<card-group>
<card icon="i-lucide-file-text" title="Stores notes as Markdown">

Notes are plain files you can edit with any editor. No lock-in, no proprietary formats.

</card>

<card icon="i-lucide-link" title="Connects ideas with links">

Relations and tags turn notes into a knowledge graph that grows over time.

</card>

<card icon="i-lucide-search" title="Lets assistants search and write">

MCP tools let your assistant read, write, search, and organize notes.

</card>

<card icon="i-lucide-cloud" title="Cloud or Local">

Use the hosted cloud service or run everything locally - your choice.

</card>
</card-group>

---

## How it works

Basic Memory stores your notes as Markdown files and keeps a search index over them. Your AI assistant connects through MCP and calls tools like `bm_search`, `bm_read`, and `bm_write` to work with your notes.

<mermaid code="flowchart LR
    subgraph You
        A[AI Assistant]
        E[Editor]
    end

    subgraph Basic Memory
        M[MCP Tools]
        I[Search Index]
    end

    subgraph Storage
        F[Markdown Files]
    end

    A <-->|MCP Tools| M
    E <-->|Edit| F
    M <-->|Read/Write| F
    M <-->|Query| I
    F -.->|Sync| I
">



</mermaid>

### The workflow

1. **Capture a note** - You write or ask your assistant to write a note during a conversation.
2. **Index and connect** - The system indexes the note, extracts observations and relations, and links it to related notes.
3. **Reuse later** - In future conversations, your assistant searches and loads relevant context automatically.

### Example conversation

```bash
You: "What did we decide about the authentication approach?"

AI: [Searches knowledge base, finds your past notes]
        "Based on your notes, you decided to use JWT tokens for API
        authentication. The decision was made on January 15th and
        documented in 'Decision: API Authentication'."

You: "Add a note about implementing refresh tokens"

AI: [Creates a new note linked to the authentication decision]
        "I've created a note about refresh tokens and linked it to
        your authentication decision notes."
```

---

## What a note looks like

Notes are standard Markdown with optional semantic structure:

```bash
---
title: API Authentication Decision
tags: [security, api, auth]
---

# API Authentication Decision

## Context
We needed to choose an authentication approach for the new API.

## Observations
- [decision] Use JWT tokens for API auth #security
- [requirement] Tokens expire after 24 hours
- [risk] Rate limiting needed on login endpoint #auth

## Relations
- implements [[API Security Spec]]
- depends_on [[User Service]]
- relates_to [[Token Refresh]]
```

**Key concepts:**

- **Observations** - Categorized facts: `[decision]`, `[requirement]`, `[risk]`, etc.
- **Relations** - Links to other notes: `[[Other Note]]` in simple WikiLink format
- **Tags** - Searchable metadata: `#security`, `#api`

<tip>

The headings '## Observations' and '## Relations' are only informative. Basic Memory will parse elements from any
where in the Markdown.

</tip>

---

## What the AI sees

When your AI assistant searches your knowledge base, it doesn't just find text - it navigates a semantic graph of connected ideas.

### The knowledge graph

Each note becomes an **entity** with structured data:

<mermaid code="flowchart LR
    E1[API Authentication] -->|implements| E2[API Security Spec]
    E1 -->|depends_on| E3[User Service]
    E1 -->|relates_to| E4[Token Refresh]
    E1 -->|decision| O1[Use JWT tokens]
    E1 -->|requirement| O2[Tokens expire in 24h]
    E1 -->|risk| O3[Rate limit logins]
">



</mermaid>

- **Entities** - Each note is an entity with a title, content, and metadata
- **Observations** - Categorized facts extracted from the note (decisions, requirements, risks)
- **Relations** - Typed links connecting entities (`implements`, `depends_on`, `relates_to`)

### Building context

When you ask a question, the AI doesn't just return one note. It traverses the graph to build rich context:

<mermaid code="flowchart LR
    Q[Your question] --> S[bm_search]
    S --> M[Matching notes]
    M --> B[bm_context]
    B --> R[Related notes]
    R --> C[Full context]
    C --> A[AI answer]
">



</mermaid>

**The flow:**

1. **Search** - Your question triggers a search across all notes
2. **Expand** - The AI uses `bm_context` to follow relations and gather connected notes
3. **Synthesize** - With the full context loaded, the AI can give a complete answer

This recursive traversal means asking about "API authentication" automatically pulls in related decisions, dependencies, and connected topics - giving your AI the full picture.

### Memory URLs

The AI references knowledge using `memory://` URLs:

```bash
memory://api-authentication          # Reference by permalink
memory://api-authentication/relates_to/*  # Follow all 'relates_to' links
memory://folder/note-title           # Reference by path
```

These stable identifiers let the AI (and you) pinpoint exactly what context to load.

<tip>

You don't have to understand or think about the object graph or relations. You can just ask the AI to manage it for you.

</tip>

```bash
You: "Make sure you add observations and relations to this note"

AI: [Update the note with semantic information]
    "OK I've updated the note with observations and relations...."

You: "Make sure you do this for all our other notes :)"

AI: [Makes a note in its own memory to keep notes annotated with semantic information]
    "I'll remember that...."
```

---

## Seeing into the black box

Built-in AI memory shows you a short digest at best - not the full context the AI draws on or how it got there. Basic Memory makes all of it transparent.

- **See what your AI sees** - Every piece of context is a file you can read
- **Edit what your AI knows** - Modify, delete, or reorganize knowledge anytime
- **Watch changes happen** - See exactly what your AI adds or updates
- **Keep your memory** - Plain Markdown files you own forever
- **Audit trail** - In the cloud, every note keeps full [version history](https://docs.basicmemory.com/cloud/file-history); locally, notes are plain files you can track with git
- **No surprises** - The AI can only know what's in your files; no hidden context
- **Portable knowledge** - Plain markdown means you're never locked in; chat with one AI, bring your knowledge to the next

---

## Closing the loop

AI agents work best when they can observe the results of their actions. Basic Memory creates a feedback loop where each conversation builds on the last.

**How it works:**

- **Cumulative intelligence** - Each conversation adds to the knowledge base, making future conversations smarter
- **Human-in-the-loop refinement** - You can correct and improve AI-generated notes, and the AI learns from your edits
- **Context compounds** - Unlike chat history that gets truncated, knowledge persists and connects
- **Pattern recognition** - Over time, the AI can recognize patterns across your entire knowledge base

### The feedback loop

<mermaid code="flowchart LR
    A[Conversation] --> B[AI writes notes]
    B --> C[You review & refine]
    C --> D[AI reads context]
    D --> A
">



</mermaid>

Each cycle reinforces learning. You ask questions, the AI searches and responds, creates notes from the conversation, and you review and refine. The knowledge base grows with each iteration.

### Knowledge refinement over time

Each conversation builds on previous context, creating increasingly refined understanding:

<mermaid code="flowchart LR
    A[Conversation 1] --> B[Memory v1]
    B --> C[Conversation 2]
    C --> D[Memory v2 · refined]
    D --> E[Conversation 3]
    E --> F[Memory v3 · richer]
">



</mermaid>

The result: your AI gets smarter about *your* work with every interaction.

---

## One memory for your whole team

Teams is the big unlock in Basic Memory Cloud: a shared workspace where one knowledge base serves you, your teammates, and every AI agent connected to it. A decision captured in one teammate's Claude session becomes context for another's Codex run. Everyone's agents read and write the same graph, so team knowledge compounds the same way personal knowledge does.

See [Basic Memory Teams](https://docs.basicmemory.com/teams/about) for workspaces, roles, and invitations.

---

## Where it runs

### Cloud

Basic Memory Cloud provides:

- **Hosted MCP endpoint** - Connect without installing anything
- **Access from any device** - Use your memory from desktop, mobile, cli, multiple AIs
- **Web app** - Browse and edit notes in your browser
- **Local sync** - Pull and push your notes to a local folder
- **Team workspaces** - one shared knowledge base for your team and all their agents
- **Snapshots** - Point-in-time backups, automatically done daily or manual as needed

### Local

The open-source local version provides:

- **Full control** - Everything runs on your machine
- **No account needed** - Use immediately after install
- **CLI tools** - Command-line access to all features
- **Offline access** - Works without internet

**Both use the same Markdown format**, so you can start with one and switch to the other later.

---

## MCP Integration

Basic Memory uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to connect with AI assistants. MCP is an open standard that lets AI assistants use external tools.

**Available tools:**

- `bm_write` - Create or update notes
- `bm_read` - Read notes with context
- `bm_search` - Full-text and semantic search
- `bm_edit` - Incremental editing
- `bm_context` - Load related notes
- `bm_project(command="list")` - List your projects
- `bm_list` and `bm_find` - Browse directories and discover paths
- `bm_man` - Read or search the built-in manual
- ...and many more

**Compatible assistants:**

- Claude Desktop
- Claude Code
- ChatGPT (Plus/Pro)
- Google Gemini
- Cursor
- VS Code (Copilot Chat)
- Codex

---

## Getting started

Ready to try Basic Memory?

<card-group>
<card icon="i-lucide-cloud" title="Quickstart: Cloud" to="https://docs.basicmemory.com/start-here/quickstart-cloud">

Connect in 2 minutes. No installation required.

</card>

<card icon="i-lucide-hard-drive" title="Quickstart: Local" to="https://docs.basicmemory.com/start-here/quickstart-local">

Install locally and run everything on your machine.

</card>
</card-group>

---

## Next steps

<card-group>
<card icon="i-lucide-rocket" title="Getting Started" to="https://docs.basicmemory.com/local/getting-started">

Set up projects and choose where your notes are saved.

</card>

<card icon="i-lucide-file-text" title="Knowledge Format" to="https://docs.basicmemory.com/concepts/knowledge-format">

Learn the note structure with observations and relations.

</card>

<card icon="i-lucide-wrench" title="MCP Tools Reference" to="https://docs.basicmemory.com/reference/mcp-tools-reference">

All available tools for AI assistants.

</card>

<card icon="i-lucide-users" title="Teams" to="https://docs.basicmemory.com/teams/about">

One shared memory for your team and every agent connected to it.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.