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

Always invoke the bm_* tools directly. Do not shell out to the bm CLI for note operations.

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:

Important: the permalink returned by bm_write already encodes the routing it needs for follow-up reads. If you wrote with project="personal/main", you get back personal/main/folder/note-slug and can call bm_read({ identifier: <that permalink> }) with no project arg. The permalink self-routes.

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.

Recipe: writing an existing file into a specific project

When the user asks something like "save this markdown file to my personal main project, return the permalink":

1. Discover the project. Call bm_projects() and find the entry matching the user's described project + workspace. You can route by either the workspace-qualified name (personal/main) or the UUID (external_id).

   bm_projects()
   # → [{name: "main", external_id: "bf2a4c1e-d77f-4b7a-9c3e-5d8a1f0e2b6d", workspace: "Personal", ...}, ...]
   

   If a project name appears in multiple workspaces, use bm_workspaces() to confirm which slug you want.

2. Read the file from disk. Use Hermes's filesystem tool (not a bm_* tool — local files aren't in the graph yet).

3. Write the note with explicit routing. Either form works; the workspace-qualified name reads cleaner in logs, the UUID is more durable.

   bm_write({
     title: "StartWithDrew Level 9 Task Queue",
     folder: "startwithdrew",
     content: <file body>,
     project: "personal/main"
   })
   # → returns "personal/main/startwithdrew/start-with-drew-level-9-task-queue"
   # (the returned permalink is workspace-qualified — carries its own routing)
   

4. Verify by reading back. No project arg needed — the workspace-qualified permalink routes itself.

   bm_read({ identifier: "personal/main/startwithdrew/start-with-drew-level-9-task-queue" })
   

Return the permalink (and the project name for clarity) to the user.

When to use each tool

Note structure

BM treats - [category] lines as observations and WikiLink lines under ## Relations as relations. Categories ([decision], [insight], [risk], [fact], [todo], …) and relation types (relates_to, implements, depends_on, blocks, …) are open-ended — use what fits the content. YAML frontmatter is supported with title, type, tags, and permalink as standard fields; any custom fields are allowed. See the knowledge format docs for the full convention.

# Clear Title

## Context
Background and current situation.

## Key Points
- Main insights
- Important details

## Observations
- [decision] We chose PostgreSQL for ACID guarantees
- [insight] Users prefer social login
- [risk] Deployment lacks rollback path

## Relations
- relates_to [[Other Note Title]]
- depends_on [[Database Choice]]

## Next Steps
- [ ] Implement
- [ ] Document

Behavior guidelines

1. Search before answering. If the user asks "what did we decide about X?", run bm_search first.
2. Offer to capture. When the user shares decisions or meeting outcomes, ask: "Should I save this as a note?"
3. Suggest connections. When a search returns related notes, surface them so the user knows what already exists.
4. Don't over-capture. Auto-capture is already running per turn. Don't create a bm_write for every response — only for substantive content the user wants preserved.
5. Sensitive info. Don't capture credentials or personal data without confirmation.

Footgun

If a note's body contains literal <memory-context>...</memory-context> tags, Hermes's streaming output scrubber will eat those tags (and the text between paired ones) when you echo the note verbatim back to the user. Tool inputs are unaffected. If you must include such content, fence it in a code block.

Further reading

Official docs live at docs.basicmemory.com. Every page has an AI-friendly raw markdown view at /raw/<path>.md (or send Accept: text/markdown to the canonical URL). WebFetch any of these when you need detail beyond what this skill covers:

• Knowledge format — observation categories, relation types, frontmatter conventions.
• Observations & relations — how notes form a graph that's searchable and traversable.
• Memory URLs — title-based addressing, wildcards (memory://docs/*), and routing resolution order.
• Projects & folders — multi-project layout, folder organization, cloud routing behavior.
• Semantic search — how bm_search resolves queries (semantic + full-text).
• MCP tools reference — Basic Memory's full MCP surface (the bm_* tools here are a curated subset).
• Cloud routing — local vs cloud project modes, per-project routing setup.
• llms.txt index — full sitemap of raw markdown pages, useful when you need to look up a page not listed above.