# https://github.com/basicmachines-co/basic-memory Project Manual

Generated at: 2026-07-07 02:54:12 UTC

## Table of Contents

- [Repository Overview & System Architecture](#page-1)
- [Markdown Format, Knowledge Graph, Indexing & Search](#page-2)
- [AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)](#page-3)
- [Cloud Sync, Projects, Deployment & Common Failure Modes](#page-4)

<a id='page-1'></a>

## Repository Overview & System Architecture

### Related Pages

Related topics: [Markdown Format, Knowledge Graph, Indexing & Search](#page-2), [AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)](#page-3), [Cloud Sync, Projects, Deployment & Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/basicmachines-co/basic-memory/blob/main/README.md)
- [docs/ARCHITECTURE.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ARCHITECTURE.md)
- [pyproject.toml](https://github.com/basicmachines-co/basic-memory/blob/main/pyproject.toml)
- [justfile](https://github.com/basicmachines-co/basic-memory/blob/main/justfile)
- [src/basic_memory/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/__init__.py)
- [src/basic_memory/api/app.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/api/app.py)
- [src/basic_memory/cli/app.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cli/app.py)
- [src/basic_memory/config.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/config.py)
- [src/basic_memory/sync/service.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/sync/service.py)
- [src/basic_memory/file_watcher.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/file_watcher.py)
- [src/basic_memory/mcp/server.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/server.py)
</details>

# Repository Overview & System Architecture

Basic Memory is a local-first, markdown-native knowledge management system designed to bridge human note-taking with AI agents. It treats plain `.md` files as the source of truth and synthesizes them into a queryable knowledge graph plus a full-text/vector search index, exposed through both an HTTP API and a Model Context Protocol (MCP) server.

## Purpose and Scope

The project's primary goal is to let users build a durable, portable "second brain" from ordinary markdown notes (Obsidian-compatible wikilinks, frontmatter, and relation annotations), while making that corpus fully accessible to LLM agents through standardized tool surfaces.

Key responsibilities:

- **Indexing pipeline** — parse markdown on disk into entities, observations, and relations, then persist them in SQLite.
- **Sync engine** — reconcile on-disk files against the database, including deletions, moves, and edits originating from external editors (e.g. Obsidian), `git pull`, or cloud sync landing files. Source: [src/basic_memory/sync/service.py:1-40]()
- **File watcher** — observe the project root for direct on-disk writes and propagate them into the index event-by-event. Source: [src/basic_memory/file_watcher.py:1-60]()
- **MCP server** — expose read/write tools (`write_note`, `read_note`, `search_notes`, `delete_entity`, etc.) so any MCP-compatible client (Claude Desktop, VS Code extensions) can drive the knowledge base.
- **CLI + HTTP API** — provide the same operations via a `bm` CLI (Typer) and a FastAPI app used by the web UI and integrations. Source: [src/basic_memory/cli/app.py:1-50]() Source: [src/basic_memory/api/app.py:1-40]()
- **Cloud sync** — optional bidirectional synchronization of project contents with hosted Basic Memory tenants (`bm cloud sync`, `bm cloud bisync`).

## Component Architecture

The runtime is layered so that each layer only depends on the one below it. A high-level view of the data and control flow:

```mermaid
flowchart TD
  A[Markdown files on disk] --> B[File Watcher / Sync Service]
  B --> C[Parser / Schema Utils]
  C --> D[(SQLite + sqlite-vec)]
  D --> E[Search & Graph API]
  E --> F[MCP Server]
  E --> G[FastAPI HTTP API]
  E --> H[bm CLI - Typer]
  F --> I[MCP Clients\nClaude Desktop, VS Code]
  G --> J[Web UI / Integrations]
  H --> K[User shell]
```

Parsing produces three core indexed shapes:

| Construct | Source on disk | Index table (logical) |
| --- | --- | --- |
| Entity | `[[Entity]]` wikilink target or file heading | `entity` |
| Observation | bullet/section under entity | `observation` |
| Relation | `- relation_type [[Other]]` | `relation` |

Source: [src/basic_memory/__init__.py:1-30]()

## Configuration, Projects, and Home

Configuration is resolved through `BasicMemoryConfig`, which honors `BASIC_MEMORY_HOME`, project-level overrides (`basic-memory.json`), and environment variables. A side effect noted in community issue #1029 is that the validator re-creates an empty default directory if it cannot resolve a project path. Source: [src/basic_memory/config.py:1-120]()

The project model is multi-tenant: each project has its own root directory, its own SQLite database, and an optional cloud workspace binding. Cross-project search is currently isolated (see community issue #123), and projects may share symlinked content only if those external roots are explicitly declared (issue #871).

## Known Architectural Friction Points

Several of the community-tracked bugs and feature gaps map directly onto subsystem boundaries:

- **Sync vs. scan error handling** — a `PermissionError` during a project scan is treated as an empty directory, triggering mass deletion of indexed paths (issue #1007). This is a boundary defect between the filesystem reader and the sync reconciler.
- **File-watcher indexing gap** — externally-written files are indexed for full-text search via the watcher, but are not vector-embedded until a reindex runs (issue #1016), exposing an asymmetry between the watcher path and the CLI/sync path.
- **Relation expansion at query time** — relations are stored as first-class rows but `search_notes` does not follow them (issue #1001), so the graph store and the retrieval layer are not yet joined.
- **`.bmignore` deletion gap** — ignore rules apply bidirectionally in cloud sync, so once content has been added to `.bmignore`, the sync engine has no supported way to delete the already-uploaded copies (issue #1032).
- **Delete endpoint coverage** — `DELETE /knowledge/entities/{id}` returns 500 for non-markdown file entities such as `.qmd`, `.csv`, `.txt` (issue #1033), reflecting an incomplete entity-type handling path in the HTTP layer.

## Build, Distribution, and Release Surface

The repository is packaged as a Python project (`src/` layout) with multiple optional dependency groups for embeddings, vector search, cloud sync, and MCP clients. The `justfile` provides recipes for lint, test, format, and release. Release artifacts include the `bm` CLI binary, the MCP server entry point, and plugins for Claude Code, Codex, and Cursor. Source: [pyproject.toml:1-80]() Source: [justfile:1-40]()

The FastAPI app is mounted both by the local CLI (`bm mcp` / `bm serve`) and by hosted cloud components, sharing the same route handlers, schemas, and database code as the local install — the only differing layer is transport and tenant isolation. Source: [src/basic_memory/api/app.py:1-80]()

In summary, Basic Memory's architecture is deliberately thin: markdown files are authoritative, every other subsystem (parser, SQLite store, vector index, MCP tools, HTTP routes, CLI) is a derived view that can be rebuilt from disk, which keeps the knowledge base portable and agent-friendly.

---

<a id='page-2'></a>

## Markdown Format, Knowledge Graph, Indexing & Search

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [Cloud Sync, Projects, Deployment & Common Failure Modes](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/NOTE-FORMAT.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/NOTE-FORMAT.md)
- [docs/semantic-search.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/semantic-search.md)
- [docs/metadata-search.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/metadata-search.md)
- [src/basic_memory/markdown/entity_parser.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/markdown/entity_parser.py)
- [src/basic_memory/markdown/markdown_processor.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/markdown/markdown_processor.py)
- [src/basic_memory/markdown/schemas.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/markdown/schemas.py)
</details>

# Markdown Format, Knowledge Graph, Indexing & Search

Basic Memory turns ordinary Markdown files into a queryable knowledge graph. Three concerns intersect: a deterministic note grammar (frontmatter + observations + relations), a parser/ingest pipeline that materializes that grammar into rows and vectors, and a search layer that combines full-text, metadata, and semantic similarity. This page covers each concern and the boundaries between them.

## Note Format and Grammar

A Basic Memory note is a Markdown document with three logical zones. The first zone is YAML frontmatter, which v0.22.1 now requires to be line-anchored (the `---` fences must sit at column 0) so that the parser cannot confuse them with a horizontal rule inside the body. Source: [src/basic_memory/markdown/file_utils.py:1-40](). Source: [docs/NOTE-FORMAT.md:1-60]().

The second zone is free-form prose, captured as the entity's `content` field. The third zone is structured metadata expressed with two list conventions:

- `- [category] Optional text` produces an *observation* row linked to the entity.
- `- relation_type [[Other Entity]]` produces a *relation* row; the wiki-link target becomes a node reference and the verb before `[[` becomes the edge type.

Source: [docs/NOTE-FORMAT.md:60-160](). The grammar is intentionally permissive: any verb is accepted, which means users invent their own relation types (`cites`, `contradicts`, `parent_of`). The trade-off is flexibility at the cost of an open schema.

The file itself may be `.md`, `.qmd`, or any text file; the `note_type` field distinguishes a Markdown *note* from a generic *file*. The per-entity delete endpoint handles both classes, but a known regression treats non-Markdown entities as 500 errors, tracked in #1033. Source: [src/basic_memory/api/routers/knowledge.py:1-120]().

## Parsing and Knowledge-Graph Construction

`entity_parser.py` converts a single file into an in-memory graph fragment. The output is a typed model defined in `schemas.py`: an `Entity` plus zero or more `Observation` and `Relation` objects. Each `Relation` carries a `from_id`, a `to_id` (the resolved entity title), and the verb as `relation_type`. Source: [src/basic_memory/markdown/schemas.py:1-120](); Source: [src/basic_memory/markdown/entity_parser.py:1-180]().

Resolution of `[[Target]]` happens by canonical title match; if the target does not yet exist as an entity, the relation is still stored, and the target row is created on first sight of its own file. This forward-reference behavior is what makes the graph write-tolerant: users can mention entities before writing their files. Source: [src/basic_memory/markdown/entity_parser.py:120-260]().

## Indexing Pipeline

`markdown_processor.py` orchestrates the write path: parse, persist entities/observations/relations to SQLite, and (for notes) emit a vector embedding for the concatenated content. The processor is invoked from two places: the MCP `write_note` tool and the local file watcher introduced under the v0.22 event-index architecture (#1002). Source: [src/basic_memory/markdown/markdown_processor.py:1-200]().

The two write paths have different coverage today. The MCP/API path emits both a row and a vector. The file-watcher path, which fires on direct on-disk writes (Obsidian, `git pull`, cloud sync landing files), indexes rows for full-text and metadata search but, as reported in #1016, does not currently call the embedding step. The practical effect is that externally-edited notes are absent from semantic search until a manual reindex. Source: [src/basic_memory/file_watcher/watcher.py:1-160]().

A second indexing pitfall documented in #1007 is that a `PermissionError` while scanning a project root is logged as a successful empty scan; the diff against the index then deletes every previously-seen entity in that project. The fix is to surface scan failures as a no-op rather than as a "nothing changed" result. Source: [src/basic_memory/sync/sync_service.py:1-180]().

## Search Layer

Search is layered. `search_notes` performs FTS-style text matching and joins results against the entity/observation/relation tables. `search` adds semantic similarity using `sqlite-vec` and the configured embedding provider (LiteLLM is supported as of v0.22.0). Source: [docs/semantic-search.md:1-80](); Source: [src/basic_memory/search/semantic.py:1-160]().

Metadata search accepts structured filters (`entity_type`, tags from frontmatter, `note_type`) and is layered on top of either text or semantic results. Source: [docs/metadata-search.md:1-120]().

A gap documented in #1001 is that relations are stored as first-class rows but never *traversed* at query time: a note one hop from a strong match is not surfaced unless its own text matches. The proposed fix is a one-hop graph expansion that unions results from neighbors of the top-k matches.

The data flow from file to query can be summarized:

```mermaid
flowchart LR
  A[Markdown file] --> B[entity_parser]
  B --> C[schemas: Entity/Observation/Relation]
  C --> D[markdown_processor]
  D --> E[(SQLite: entities, observations, relations)]
  D --> F[(sqlite-vec: embeddings)]
  E --> G[search_notes / metadata search]
  F --> H[semantic search]
  G --> I[Results]
  H --> I[Results]
```

## Practical Implications

Three patterns follow from the design. First, keep relations human-readable: the verb in front of `[[X]]` is the only thing preserved, so `mentioned [[Alice]]` and `cites [[Alice]]` produce different edges with different retrieval behavior. Second, choose the write path deliberately: notes that must be semantically searchable should be created via the MCP/API rather than edited on disk, until the file-watcher embedding gap (#1016) is closed. Third, treat the knowledge graph as the source of truth for entity identity, not the filesystem path: a renamed file that keeps the same frontmatter title does not create a new node.

---

<a id='page-3'></a>

## AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [Markdown Format, Knowledge Graph, Indexing & Search](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/basic_memory/mcp/server.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/server.py)
- [src/basic_memory/mcp/tools/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/__init__.py)
- [src/basic_memory/plugins/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/plugins/__init__.py)
- [src/basic_memory/plugins/claude_code.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/plugins/claude_code.py)
- [src/basic_memory/plugins/codex.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/plugins/codex.py)
- [src/basic_memory/plugins/hermes.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/plugins/hermes.py)
- [src/basic_memory/plugins/openclaw.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/plugins/openclaw.py)
- [src/basic_memory/skills/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/skills/__init__.py)
- [src/basic_memory/skills/loader.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/skills/loader.py)
- [src/basic_memory/skills/models.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/skills/models.py)
- [src/basic_memory/skills/registry.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/skills/registry.py)
- [src/basic_memory/cli/commands/install.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cli/commands/install.py)
</details>

# AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)

Basic Memory exposes its knowledge base to AI coding assistants through a layered integration architecture: an MCP server at the core, client-specific plugins that adapt that server to each assistant's installation conventions, and a Skills layer that packages domain knowledge (with frontmatter) into reusable instruction bundles. Together, these components let Claude Code, Codex, Hermes, and OpenClaw treat a project's local Markdown files as a persistent, queryable memory.

## Architecture Overview

The integration stack is organized so that each AI client speaks a single common protocol to Basic Memory, while per-client quirks are isolated in the `plugins/` package.

| Layer | Purpose | Key files |
|---|---|---|
| MCP server | Exposes `read_note`, `write_note`, `edit_note`, `move_note`, `search_notes`, etc. as tools | `src/basic_memory/mcp/server.py`, `src/basic_memory/mcp/tools/__init__.py` |
| Plugins | Register the MCP server with each AI client's installation/conventions | `src/basic_memory/plugins/claude_code.py`, `codex.py`, `hermes.py`, `openclaw.py` |
| Skills | Bundle prompt-level instructions + frontmatter into named capabilities loaded at session start | `src/basic_memory/skills/loader.py`, `models.py`, `registry.py` |
| CLI installer | Wires the plugin + skills into the user's environment | `src/basic_memory/cli/commands/install.py` |

Source: [src/basic_memory/mcp/server.py:1-40](), [src/basic_memory/plugins/__init__.py:1-30](), [src/basic_memory/skills/__init__.py:1-25]().

## MCP Server (Core Protocol Surface)

The MCP server in `src/basic_memory/mcp/server.py` is the single contract every plugin consumes. It registers tool handlers defined in `src/basic_memory/mcp/tools/__init__.py`, where each tool (write/read/edit/move) wraps a service-layer call and returns structured responses that AI agents can reason over. Because all clients go through this same surface, a plugin only needs to handle installation and configuration — not tool semantics.

Source: [src/basic_memory/mcp/server.py:40-120](), [src/basic_memory/mcp/tools/__init__.py:1-60]().

## Client-Specific Plugins

Each plugin in `src/basic_memory/plugins/` adapts the MCP server to a particular assistant's config layout and startup flow. The `__init__.py` exposes a registry-style entry point so `bm install <client>` can dispatch to the right module.

- **Claude Code** (`claude_code.py`): registers Basic Memory as an MCP server in Claude Code's settings, pointing at the local Python entry point.
- **Codex** (`codex.py`): wires the same MCP server into Codex's configuration; release v0.22.0 specifically fixed shared version bumping so Codex stays in lockstep with other clients (`fix(plugins): include codex in shared version bump`, PR #897).
- **Hermes** (`hermes.py`): installs the MCP endpoint using Hermes' configuration conventions.
- **OpenClaw** (`openclaw.py`): provides the registration glue for OpenClaw-based assistants.

Source: [src/basic_memory/plugins/claude_code.py:1-80](), [src/basic_memory/plugins/codex.py:1-80](), [src/basic_memory/plugins/hermes.py:1-80](), [src/basic_memory/plugins/openclaw.py:1-80]().

Plugins are intentionally thin: they never embed tool logic. That separation means fixes to the MCP server (for example, line-anchored frontmatter parsing in `file_utils` shipped in v0.22.1) propagate to every client simultaneously.

## Skills System

Skills sit one layer above raw MCP tools: they are Markdown documents with YAML frontmatter that describe *how* an assistant should use the tools to accomplish a higher-level task (e.g., "summarize a project", "synthesize a research note"). The skills package has three responsibilities:

1. **Models** (`models.py`) — defines the `Skill` schema, including the frontmatter fields name, description, and version.
2. **Loader** (`loader.py`) — discovers skill files on disk, parses frontmatter, and validates structure. v0.22.0 introduced `fix(skills): reject invalid frontmatter YAML` (PR #896) so malformed skills fail loudly instead of silently breaking.
3. **Registry** (`registry.py`) — exposes loaded skills by name to the MCP server so a client can list or invoke them at session start.

Source: [src/basic_memory/skills/models.py:1-60](), [src/basic_memory/skills/loader.py:1-90](), [src/basic_memory/skills/registry.py:1-50]().

## Installation Flow

The CLI command `bm install <client>` (defined in `src/basic_memory/cli/commands/install.py`) is the user-facing entry point. It calls the chosen plugin, copies or symlinks the MCP server entry point into the client's expected config directory, and registers active skills from the user's project so they are available to the assistant on next launch. Because every plugin returns the same registration payload, additional clients can be supported by adding a new module under `src/basic_memory/plugins/` without touching the MCP server or skills code.

Source: [src/basic_memory/cli/commands/install.py:1-120]().

## Related Community Discussions

- Cross-project search (#123) and relation-traversal search (#1001) would be exposed through the same MCP tools that these plugins register, so any improvement to the tool surface benefits every client.
- Auto-commit via the watch service (#54) is relevant because the file-watcher path (#1016) feeds content into the same indexed corpus that the MCP `search_notes` and `read_note` tools return to every AI client plugin.
- The recent v0.22.0 and v0.22.1 releases both shipped fixes touching this stack: invalid frontmatter rejection in skills and codex version-bump inclusion in plugins — evidence that the integration layer is actively maintained.

---

<a id='page-4'></a>

## Cloud Sync, Projects, Deployment & Common Failure Modes

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [Markdown Format, Knowledge Graph, Indexing & Search](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/cloud-cli.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/cloud-cli.md)
- [docs/SPEC-PER-PROJECT-ROUTING.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/SPEC-PER-PROJECT-ROUTING.md)
- [docs/Docker.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/Docker.md)
- [Dockerfile](https://github.com/basicmachines-co/basic-memory/blob/main/Dockerfile)
- [src/basic_memory/cli/cloud.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cli/cloud.py)
- [src/basic_memory/config.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/config.py)
- [src/basic_memory/file_watcher.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/file_watcher.py)
- [src/basic_memory/sync/sync_service.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/sync/sync_service.py)
- [src/basic_memory/utils.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/utils.py)
</details>

# Cloud Sync, Projects, Deployment & Common Failure Modes

Basic Memory provides a multi-project, multi-tenant model in which a single local installation can host many independent knowledge bases ("projects") and selectively synchronize any of them with a hosted cloud tenant. The cloud CLI, the per-project routing specification, and the Docker image together form the deployment surface that ties filesystem events, the SQLite index, and the cloud sync engine into one operational pipeline.

## Projects and Per-Project Routing

A *project* is a configured root directory plus its own SQLite database, watched by an independent file-watcher. The routing specification defines how incoming requests, write operations, and search queries are dispatched to the correct project, enforcing strict isolation by default. `Source: [docs/SPEC-PER-PROJECT-ROUTING.md:1-80]()`

The CLI exposes project lifecycle commands such as `bm project add`, `bm project list`, `bm project remove`, and `bm project default`. By design, `bm project remove` only deregisters the project from the local configuration; the underlying markdown files are left on disk so users do not lose source material through a typo. `Source: [src/basic_memory/cli/cloud.py:120-180]()`

The configuration layer reads `~/.basic-memory/config.yaml` (or the path overridden by `BASIC_MEMORY_HOME`) and validates each project's `home` field. Historically, this validator invoked `mkdir` on the default `~/basic-memory` path even when the operator had configured an entirely different project root, producing a stray empty directory on every config load. This mkdir side effect is tracked as a known papercut and is the kind of deployment artifact operators should look for during troubleshooting. `Source: [src/basic_memory/config.py:55-110]()` Related community thread: [issue #1029](https://github.com/basicmachines-co/basic-memory/issues/1029).

Cross-project workflows are intentionally restricted. There is no built-in "search across all projects" path; the enhancement request for cross-project search and entity linking captures the demand but is not yet part of the supported surface. `Source: [docs/SPEC-PER-PROJECT-ROUTING.md:180-230]()` Related community thread: [issue #123](https://github.com/basicmachines-co/basic-memory/issues/123).

## Cloud Sync Engine

The cloud sync subsystem supports two modes: one-way mirroring (`bm cloud sync`) and bidirectional sync (`bm cloud bisync`), both implemented over rclone-style remotes that target a per-project tenant in the hosted cloud. A `.bmignore` file in the project root is honored on both the local and remote sides of the pipeline; matching paths are neither uploaded nor deleted by the engine. `Source: [src/basic_memory/sync/sync_service.py:1-90]()`

The sync service also exposes support metadata so operators can detect, before launching a long-running job, whether the chosen project is eligible for cloud synchronization. `Source: [src/basic_memory/cli/cloud.py:200-260]()` Related release note: [v0.21.6 — feat(cli): expose project sync support metadata](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.6).

Because `.bmignore` filters on both ends of the transfer, content that has already synced to a hosted tenant becomes effectively undeletable from cloud once an ignore rule is added locally. This is documented behavior but is also a known sharp edge called out by users. `Source: [src/basic_memory/sync/sync_service.py:90-160]()` Related community thread: [issue #1032](https://github.com/basicmachines-co/basic-memory/issues/1032).

## Deployment (Docker and Local)

The official `Dockerfile` packages the CLI, the MCP server, and the ASGI app into a single image, exposing the ports required by the local API and the file watcher. Deployment is typically one of:

- **Local install**: `pip install basic-memory`, then `bm project add <path>` to register knowledge roots.
- **Container**: build the image and mount the project directory read-write so the in-container file watcher and SQLite index see live edits.
`Source: [Dockerfile:1-60]()` `Source: [docs/Docker.md:1-80]()`

Team workspaces have a deliberately blocked rclone path; the CLI refuses cloud sync against a team workspace to prevent accidental cross-tenant writes. `Source: [src/basic_memory/cli/cloud.py:260-310]()` Related release note: [v0.21.6 — fix(cli): block team workspace rclone sync](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.6).

## Common Failure Modes

The following patterns recur in operator reports and are worth checking before opening a support ticket:

1. **Mass index deletion on scan failure.** A `PermissionError` raised while listing the project root is silently treated as an empty directory; the subsequent reconciliation then deletes every indexed entity. Operators should confirm directory permissions and rerun `bm sync` after restoring access. `Source: [src/basic_memory/sync/sync_service.py:160-230]()` Related community thread: [issue #1007](https://github.com/basicmachines-co/basic-memory/issues/1007).

2. **File-watcher writes missing from semantic search.** Notes written directly to disk (Obsidian, editor, `git pull`, cloud sync landing files) are captured by the watcher for full-text search but are not automatically vector-embedded, so they remain invisible to semantic queries until a reindex runs. `Source: [src/basic_memory/file_watcher.py:1-120]()` Related community thread: [issue #1016](https://github.com/basicmachines-co/basic-memory/issues/1016).

3. **Opaque errors on large cloud-project deletion.** Removing a large hosted project surfaces generic errors rather than per-object progress, and there is no documented purge path for orphaned tenant data. `Source: [src/basic_memory/cli/cloud.py:310-360]()` Related community thread: [issue #1034](https://github.com/basicmachines-co/basic-memory/issues/1034).

4. **Non-markdown entity delete returns 500.** The per-entity `DELETE /knowledge/entities/{id}` endpoint only handles markdown note-entities; file-type entities (`.qmd`, `.csv`, `.py`, `.txt`, `.yml`, sync-conflict files) trigger a 500. Bulk delete via `POST /knowledge/delete` is the supported alternative. `Source: [src/basic_memory/utils.py:1-60]()` Related community thread: [issue #1033](https://github.com/basicmachines-co/basic-memory/issues/1033).

5. **Symlinks outside the project root are not followed.** Symlinks resolving outside the declared project root are rejected by the watcher for safety. Operators who need to blend shared, org-level notes into a project must either place them inside the project root or request the additional-knowledge-root feature. `Source: [src/basic_memory/file_watcher.py:120-200]()` Related community thread: [issue #871](https://github.com/basicmachines-co/basic-memory/issues/871).

For destructive operations in general, the community has long requested a Git-based undo/recovery layer over the file watcher so that file moves and bulk edits can be rolled back. Until that ships, operators are advised to keep their project roots under version control. `Source: [docs/SPEC-PER-PROJECT-ROUTING.md:230-280]()` Related community thread: [issue #124](https://github.com/basicmachines-co/basic-memory/issues/124) and [issue #54](https://github.com/basicmachines-co/basic-memory/issues/54).

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: basicmachines-co/basic-memory

Summary: Found 15 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1001

## 2. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1016

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1034

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1007

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/871

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1029

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/basicmachines-co/basic-memory

## 8. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/basicmachines-co/basic-memory

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/basicmachines-co/basic-memory

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/basicmachines-co/basic-memory

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1032

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1033

## 14. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory

<!-- canonical_name: basicmachines-co/basic-memory; human_manual_source: deepwiki_human_wiki -->