com um clique
basic-memory
// Use the Basic Memory knowledge graph for persistent memory across sessions. Search before answering; capture decisions, meetings, and insights as notes.
// Use the Basic Memory knowledge graph for persistent memory across sessions. Search before answering; capture decisions, meetings, and insights as notes.
| name | basic-memory |
| description | Use the Basic Memory knowledge graph for persistent memory across sessions. Search before answering; capture decisions, meetings, and insights as notes. |
| category | memory |
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.
bm_*, not the bm CLIAlways 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:
| 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 |
bm_search — search the graphUse 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 contentAfter 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:// URLsReturns the target note plus related notes via traversed relations.
bm_context({ url: "memory://projects/api-redesign", depth: 1 })
bm_write — capture new knowledgeWhen 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 updatesOperations: 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 — maintenanceUse sparingly. bm_move takes new_folder.
bm_recent — what's been touched latelyReturns 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 projectsReturns 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 workspacesWorkspaces 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()
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. |
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.
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.
When the user asks something like "save this markdown file to my personal main project, return the permalink":
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.
Read the file from disk. Use Hermes's filesystem tool (not a bm_* tool — local files aren't in the graph yet).
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)
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.
| 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 directly — it already encodes the routing |
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
bm_search first.bm_write for every response — only for substantive content the user wants preserved.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.
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:
memory://docs/*), and routing resolution order.bm_search resolves queries (semantic + full-text).bm_* tools here are a curated subset).