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:

Use case	Tool (not CLI)
Search the graph	bm_search
Read a note	bm_read
Create / update a note	bm_write / bm_edit
Navigate relations	bm_context
Move / delete	bm_move / bm_delete
What's been touched lately	bm_recent
List available projects	bm_projects
List cloud workspaces	bm_workspaces

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:

Shape	Example	When
Short	decisions/auth-strategy	Bare folder/note-slug. Tools need a project (or project_id) arg to route — the permalink alone isn't enough.
Project-qualified	main/decisions/auth-strategy	project-name/folder/note-slug. Carries enough context to route without a separate project arg.
Workspace-qualified	personal/main/decisions/auth-strategy	workspace-slug/project-name/folder/note-slug. Fully routes, including across cloud workspaces with same-named projects.

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.

When to use each tool

Situation	Tool
User asks about a topic that might already be documented	bm_search first, then bm_read
User exposes a decision, plan, or meeting outcome	offer to bm_write
Updating prior work	bm_edit (append for time-ordered logs, replace_section for living docs)
Exploring related concepts	bm_context
"What was I working on yesterday?" / no specific query yet	bm_recent
User names a project that isn't the active one	bm_projects → call read/write tool with project: "workspace/name" or project_id: "<uuid>"
Same project name might exist in multiple workspaces	bm_projects (+ bm_workspaces if needed) → route with workspace-qualified project or project_id
Following up on a freshly-written note	Use the returned permalink with the same project / project_id as the write (workspace-qualified permalinks need neither)

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. Never claim an unwritten save. "Remember/record/save/note this" means calling bm_write (or bm_edit) in that turn. Only report a save after the tool returned a result, and quote the returned permalink — never a filename recalled from memory.
4. Suggest connections. When a search returns related notes, surface them so the user knows what already exists.
5. 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.
6. 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.