Basic Memory

Basic Memory Knowledge Graph

You have access to a persistent knowledge graph backed by Basic Memory. The graph survives across sessions and is shared with other tools (Claude Desktop, Obsidian, the bm CLI). Use the bm_* tools below to recall and capture information.

Use bm_*, not the bm CLI

Use the bm_* tools for note operations rather than shelling out to the bm CLI.

The bm_* tools route through a persistent MCP connection — roughly 0.1 seconds per call. Running bm from the shell spawns a fresh Python process per call (1-2 seconds of cold-start every time) and bypasses Hermes's automatic per-turn capture, so the session-transcript and summary notes won't reflect what you did.

The CLI is fine when you genuinely need a feature these wrappers don't expose (rare). Otherwise, prefer:

Tool reference

bm_search — search the graph

Use before answering questions about prior decisions, projects, meetings, or anything that might already be documented.

bm_search({ query: "auth strategy decision", limit: 5 })

bm_read — fetch a note's full content

After search shows a relevant note, read it for context.

bm_read({ identifier: "decisions/auth-strategy" })
bm_read({ identifier: "memory://projects/api-redesign" })

bm_context — navigate via memory:// URLs

Returns the target note plus related notes via traversed relations.

bm_context({ url: "memory://projects/api-redesign", depth: 1 })

bm_write — capture new knowledge

When the user shares a decision, meeting outcome, or insight worth keeping, capture it. Use clear titles and a folder.

bm_write({
  title: "API Authentication Decision",
  folder: "decisions",
  content: "# API Authentication\n\n## Context\n...\n\n## Decision\n..."
})

Recommended folders: projects/, decisions/, meetings/, concepts/, weekly/.

bm_edit — incremental updates

Operations: append, prepend, find_replace (requires find_text), replace_section (requires section).

bm_edit({
  identifier: "projects/api-redesign",
  operation: "append",
  content: "\n## Update 2026-05-09\nDeployed to staging."
})

bm_delete / bm_move — maintenance

Use sparingly. bm_move takes new_folder.

bm_recent — what's been touched lately

Returns notes updated within a window. Use when there's no specific query yet — e.g. "what was I working on yesterday?"

bm_recent({ timeframe: "7d" })
bm_recent({ timeframe: "yesterday", limit: 20 })
bm_recent({ timeframe: "2 weeks", type: "entity" })

timeframe accepts natural language ("yesterday", "2 weeks", "last month") or compact forms ("7d", "24h"). Default is 7d.

bm_projects — list available projects

Returns name, workspace slug, and external_id (UUID) per project across local and cloud. Call this when the user names a project that isn't the active one. Route follow-up tool calls either by workspace-qualified name (project: "personal/main") or by UUID (project_id: "bf2a4c1e-d77f-...") — see Cross-project routing below.

bm_projects()

bm_workspaces — list BM Cloud workspaces

Workspaces are a BM Cloud concept. Returns name, type, role, and default flag. Pair with bm_projects when the same project name might exist in more than one workspace and you need to disambiguate.

bm_workspaces()

Permalinks

A permalink is the canonical, URL-friendly identifier for a note. Three shapes exist; the read/write tools accept all of them:

Only a workspace-qualified permalink routes by itself. A cloud write with project="personal/main" returns personal/main/folder/note-slug, which bm_read({ identifier: <that permalink> }) can follow with no project arg. A local write returns a short permalink such as folder/note-slug; to read it back, pass the same project or project_id you used for bm_write, or the call falls back to the active project.

memory:// URLs follow the same shapes: memory://personal/main/decisions/auth-strategy is valid. The memory:// prefix is optional for bm_read (any of the three permalink shapes works directly); bm_context expects the prefix.

Cross-project routing

Every read/write tool (bm_search, bm_read, bm_write, bm_edit, bm_context, bm_delete, bm_move, bm_recent) accepts optional project and project_id:

• project — project name, optionally workspace-qualified. Plain ("main") when the name is globally unique; qualified ("personal/main", "team-paul/research") when you need to pick a specific cloud workspace by slug.
• project_id — UUID from bm_projects (external_id field). The most stable identifier — survives project renames and works across workspaces without qualification. Wins over project if both are passed.

Omit both and the call uses the Hermes-configured active project.

# Plain project name (unique)
bm_write({ title: "...", folder: "...", content: "...", project: "main" })

# Workspace-qualified name (disambiguates same-named projects across workspaces)
bm_write({ title: "...", folder: "...", content: "...", project: "personal/main" })

# UUID (most stable, survives renames)
bm_write({ title: "...", folder: "...", content: "...", project_id: "bf2a4c1e-d77f-..." })

bm_projects and bm_workspaces themselves do not take routing — they list across everything.

To save into a named project: find it with bm_projects, write with explicit project or project_id, and return the permalink bm_write gives back. Follow-up reads need the same project or project_id unless that permalink is workspace-qualified.