--- title: "User Guide" description: "Learn how to effectively use Basic Memory in your daily workflow to build rich semantic knowledge." canonical_url: "https://docs.basicmemory.com/local/user-guide" --- # User Guide > Learn how to effectively use Basic Memory in your daily workflow to build rich semantic knowledge. This guide covers everything from creating your first notes to building a comprehensive knowledge graph. Using Basic Memory Cloud? Your notes are automatically synced and accessible from anywhere. See the [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) for setup and the [Web App](https://docs.basicmemory.com/cloud/web-app) for browser-based editing. --- ## Basic Memory Workflow Using Basic Memory follows a natural cycle: 1. **Have conversations** with AI assistants like Claude 2. **Capture knowledge** in Markdown files 3. **Build connections** between pieces of knowledge 4. **Reference your knowledge** in future conversations 5. **Edit files directly** when needed 6. **Sync changes** automatically --- ## Creating Knowledge ### Through Conversations The most natural way to create knowledge is during conversations: ```bash You: We've covered several authentication approaches. Could you create a note summarizing what we've discussed? Claude: I'll create a note summarizing our authentication discussion. [Uses bm_write tool] Done! I've created "Authentication Approaches.md" with: - Overview of options we discussed - Observations about JWT vs sessions - Relations to your security notes ``` This creates a Markdown file with semantic markup in your knowledge base. You can store your knowledge at any location. `~/basic-memory` is the default project location. See [Getting Started](https://docs.basicmemory.com/local/getting-started#choosing-where-notes-are-saved) for more information. ### Direct File Creation You can also create files directly: 1. Create a new Markdown file in your project directory 2. Add frontmatter with title, type, and optional tags 3. Structure content with observations and relations 4. Save the file - it syncs automatically **Example file structure:** ```bash --- title: API Design Decisions tags: [api, architecture, decisions] --- # API Design Decisions ## Context We needed to choose an approach for the new API. ## Observations - [decision] Use REST over GraphQL for simplicity #api - [requirement] Must support versioning from day one - [risk] Rate limiting needed for public endpoints ## Relations - implements [[API Specification]] - depends_on [[Authentication System]] ``` Standard Markdown links to other files in the project, such as `[the spec](../specs/API%20Specification.md)`, also become `links_to` relations, so notes written in other editors connect without converting their links. --- ## Using Special Prompts Basic Memory includes special prompts that help you leverage your knowledge base effectively. ### Continue Conversation Resume previous topics with full context: ```bash "Let's continue our conversation about [topic]" ``` **What happens:** - Searches your knowledge base for relevant content - Builds context from related documents - Resumes with awareness of previous discussions ### Recent Activity See what you've been working on: ```bash "What have we been discussing recently?" ``` **What happens:** - Retrieves recently modified documents - Summarizes main topics and points - Offers to continue any discussions ### Search Find specific information: ```bash "Find information about [topic]" ``` **What happens:** - Searches across all your documents - Summarizes key findings - Offers to explore specific documents --- ## Working with Memory URLs Basic Memory uses special `memory://` URLs to reference knowledge: ```bash memory://coffee-brewing-methods # Reference by permalink memory://coffee-brewing-methods/relates_to/* # Follow relations ``` See [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls) for the full addressing syntax, including project-prefixed forms. ### Using Memory URLs Reference existing knowledge in conversations: ```bash You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements" ``` Claude will load that specific document and any related context. Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same (unless you enable `update_permalinks_on_move` — see [Configuration](https://docs.basicmemory.com/reference/configuration)). --- ## Memory URL resolution (local server) At runtime, the local MCP server resolves memory URLs in this order: ### 1. Project constraints If the MCP server was started with `BASIC_MEMORY_MCP_PROJECT=research`, unprefixed URLs (and URLs prefixed with `research`) resolve in the `research` project. A URL prefixed with a *different* known project returns an error rather than resolving: ```text memory://docs/auth → resolves in "research" memory://main/docs/auth → error: project is constrained to "research" ``` ### 2. Explicit project prefix If no constraint is set, the URL is checked for a project prefix. The longest matching known project prefix is stripped and used as the project context: ```text memory://main/specs/api-design ^^^^ → project = "main" ^^^^^^^^^^^^^^^^ → path = "specs/api-design" ``` If no known project prefix matches, the entire path is treated as a note path and still needs project scope. ### 3. Explicit scope or a single addressable project If no constraint exists and no project prefix matches, pass `project` explicitly when several projects are addressable. A configured default does not remove this requirement for 1.0 note and search tools. With only one addressable project, the tools can use it implicitly. ```python bm_read(identifier="memory://docs/auth", project="main") ``` Prefix detection always runs — it isn't controlled by configuration. The `permalinks_include_project` setting governs whether *generated permalinks* include the project slug; see [Configuration](https://docs.basicmemory.com/reference/configuration). --- ## Building Knowledge Connections Connect knowledge with relations and structure facts with categorized observations: ```markdown ## Observations - [decision] We chose JWT tokens for stateless auth - [requirement] Must support 2FA for sensitive operations ## Relations - implements [[Authentication System]] - requires [[Database Schema]] ``` Categories and relation types are open-ended — use whatever fits. The full syntax, conventions, and edge cases live in [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations). ### Dating facts When a fact is only true for a period, say so right after the category (new in [v0.24](https://docs.basicmemory.com/whats-new/v0-24)): ```markdown - [decision] @effective:2026-06-10 Cache layer uses Redis - [policy] @effective[2026-01-01,2026-07-01) Weekly releases on Tuesdays - [incident] @occurred:"June 10, 2026" Primary database failed over - [deadline] @due:2026-09-30 Ship the migration tooling ``` Your AI can then ask what was true at a point in time — "which caching decision was in effect on July 1st?" — using the `valid_at`, `valid_overlaps`, and `time_kind` search filters. See [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations#when-a-fact-holds-valid-time) for the syntax and [Metadata Search](https://docs.basicmemory.com/concepts/metadata-search#searching-by-valid-time) for the filters. ### When notes are deleted Deleting a note keeps the links that pointed at it as unresolved references instead of erasing them. Recreate the note (same title or path) and those links reconnect. --- ## Multi-Project Workflows Basic Memory supports multiple projects for organizing different knowledge bases. The AI discovers your projects with `bm_project(command="list")` and names the project on each tool call; unqualified note and search calls are refused when several projects are addressable, even if a default exists. There's no per-session "active project". Project setup and CLI default-project commands are covered in [Set Up Local Projects](https://docs.basicmemory.com/local/getting-started). ### Single Project Mode (Locked) For focused sessions or automation, lock the MCP server to one project: ```bash basic-memory mcp --project work-notes ``` This **locks** the entire MCP session to that project. Unqualified calls use it; targets naming a different known project are refused. **When to use:** - Automation workflows that should only access one project - Focused sessions where you want to prevent cross-project operations - Team environments with project-specific access **Key difference:** - **Unconstrained MCP server**: With several addressable projects, pass `project` or a project-qualified target on note and search calls - **Single Project Mode**: Locked to one project, cannot switch ### Searching Across Projects Ask your AI to search several projects at once — "search my work and research projects for rate limiting". It passes `projects=["work", "research"]` (or `all_projects=True` for everything) to `bm_search` and gets one ranked list, with each result labeled by project. ### Moving Notes Between Projects Moving notes from one project to another is not currently supported directly. The easiest approach is to: 1. Copy the file manually between project directories 2. Or create a new note in the destination project, then delete the original --- ## File Organization ### Directory Structure Organize files in any structure that suits you: ```bash ~/basic-memory/ ├── projects/ # Active project notes │ ├── api-redesign/ │ └── mobile-app/ ├── decisions/ # Decision records ├── learning/ # Research and learning notes ├── meetings/ # Meeting notes └── archive/ # Completed/old content ``` ### Best Practices - Use descriptive filenames - Group related content in folders - Include dates in time-sensitive notes (e.g., `2024-01-15 Team Standup.md`) - Archive old content regularly ### Controlling What Gets Indexed Basic Memory respects `.gitignore` patterns to skip sensitive files. **Pattern sources:** - **Global patterns**: `~/.basic-memory/.bmignore` (all projects) - **Project patterns**: `{project}/.gitignore` (specific project) **Example .gitignore:** ```gitignore # Sensitive files .env *.key credentials.json # Build artifacts node_modules/ __pycache__/ dist/ # OS files .DS_Store Thumbs.db ``` Files matching these patterns are automatically skipped during indexing. Indexing doesn't remove notes that were already indexed before you added a pattern. To clean those up, run `bm prune`: it lists the index entries the current `.bmignore` and `.gitignore` now exclude and asks before removing them (`--dry-run` to preview, `--yes` to skip the prompt). Your files are not touched. ### Documents, PDFs, and Other Files Non-Markdown files in a project — PDFs, images, Office documents — are indexed as files you can list, read, link to, and move. To make a document's text searchable, extract it into a Markdown note next to it: ```bash uv tool install 'basic-memory[pdf,documents]' # PDF, Word, PowerPoint support bm import document reports/q3-review.pdf # path relative to the project root ``` This writes `reports/q3-review.pdf.md` with the extracted text and a provenance note under `document-ingestion-runs/`. CSV files work without an extra. See [Documents and PDFs](https://docs.basicmemory.com/concepts/documents-and-pdfs). ### Navigation Pages and Export `bm wiki rebuild` generates `index.md` and `log.md` navigation pages for the project root and each folder — useful when browsing a project on GitHub or in an editor — without overwriting pages you wrote yourself. `bm okf export` writes a project as a static Open Knowledge Format bundle. See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference). --- ## Enhanced Editing ### Incremental Editing Edit notes without rewriting entire documents: ```bash You: "Add a troubleshooting section to my setup guide" Claude: [Uses bm_edit with append operation] "I've added a troubleshooting section to the end of your setup guide." ``` **Available operations:** - `append` - Add content to end - `prepend` - Add content to beginning - `find_replace` - Replace specific text - `replace_section` - Replace entire section by heading (fails if the exact heading isn't in the note — use `append` to add a new section) - `insert_before_section` / `insert_after_section` - Insert content adjacent to a section heading ### Protecting Notes from Edits Add `locked: true` to a note's frontmatter to make it read-only to Basic Memory's tools: ```yaml --- title: Release Runbook locked: true --- ``` Writes, edits, overwrites, and deletes through the AI tools, CLI, or API are refused (HTTP `423`), and deleting a folder that contains a locked note is refused before anything is deleted. Reads, search, and moves still work. No tool call can unlock a note — edit the file directly and remove the line. Direct file edits and imports aren't blocked, so this guards against accidental AI changes rather than acting as access control. See [Knowledge Format](https://docs.basicmemory.com/concepts/knowledge-format#locked-notes). ### Smart File Organization Move and rename notes with database consistency: ```bash You: "Move my old meeting notes to the archive folder" Claude: [Uses bm_move] "Done! I've moved 12 meeting notes to the archive folder." ``` ### Directory Operations Move or delete entire folders: ```bash You: "Move the old-projects folder to archive" Claude: [Uses bm_move with path="old-projects", destination="archive/", project="main"] "Moved old-projects/ → archive/old-projects/ (15 files)" You: "Delete the temp folder and its contents" Claude: [Uses bm_delete with path="temp", recursive=True, project="main"] "Deleted temp/ and all 3 contained files" ``` ### Enhanced Search Tags and frontmatter fields are searchable. Use `tag:` shorthand or metadata filters to narrow results: ```bash You: "Find all my notes tagged with security" Claude: [Uses bm_search with query="tag:security"] You: "Show me in-progress specs" Claude: [Uses bm_search with note_types=["spec"], filters={"status": "in-progress"}] You: "Find high priority items from this year" Claude: [Uses bm_search with filters={"priority": {"$in": ["high", "critical"]}}, since="2026-01-01"] You: "Which specs don't have an owner yet?" Claude: [Uses bm_search with note_types=["spec"], filters={"owner": {"$exists": false}}] You: "What decisions were in effect on July 1st?" Claude: [Uses bm_search with categories=["decision"], valid_at="2026-07-01"] ``` You can also search purely by metadata — no text query needed: ```bash You: "What notes have status draft?" Claude: [Uses bm_search with filters={"status": "draft"}] ``` --- ## Schema Workflows As your knowledge base grows, you may want consistent structure for certain note types. Schemas let you define what a "good" note of a particular type should contain, then validate notes against that definition. **Conversational example:** ```bash You: "I've been writing a lot of person notes. Can you help me standardize them?" Claude: Let me analyze your existing person notes to find common patterns. [Uses bm_schema with command="infer", note_type="person"] Based on your notes, here's what most of them include: - name (in 95% of notes) - role (in 80%) - works_at relation (in 60%) I can create a schema note that formalizes this pattern. Would you like me to save it? You: "Yes, and validate my existing notes against it" Claude: [Creates schema note, then validates] 3 of your 15 person notes are missing the [name] observation. Here are the ones that need updating... ``` See the [Schema System](https://docs.basicmemory.com/concepts/schema-system) guide for full details on picoschema syntax, validation modes, and the infer-validate-diff lifecycle. --- ## Semantic Search Semantic search lets you find notes by meaning rather than exact keywords. This is helpful when you remember the concept but not the exact words used in the note. **Conversational example:** ```bash You: "Find my notes about making the app faster" Claude: [Uses bm_search with mode="hybrid"] I found several relevant notes: 1. "React Performance Optimization" — contains observations about bundle size and lazy loading 2. "Database Query Tuning" — discusses index strategies and query plans 3. "Caching Architecture" — your design decisions for the Redis cache layer Would you like me to build context from any of these? ``` Semantic search is always on — as of v0.24 there's no setting to disable it. Embeddings are generated automatically on first startup. Full-text search also handles Chinese, Japanese, Korean, Thai, and other languages written without spaces. See the [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) guide for configuration details, including local OpenAI-compatible embedding servers. --- ## Syncing and Updates ### Real-time Sync Basic Memory automatically syncs file changes in real-time. When you edit a file in your editor: 1. The change is detected within ~1 second 2. The file is re-parsed for observations and relations 3. The database is updated 4. Search index is refreshed No manual sync needed for normal workflows. ### Checking Status ```bash # View project index status basic-memory status # Wait until files, relations, and embeddings have all finished indexing basic-memory status --wait # View project information basic-memory project info main ``` `bm project add` indexes a new local project before it returns, and `bm project index ` reindexes one project on demand. ### Force Re-sync Sync runs automatically — file changes are picked up in real time. If something still seems out of sync: ```bash # Rebuild the search index basic-memory reindex # Reset and rebuild the database (use if issues persist) basic-memory reset --reindex ``` `basic-memory reset` deletes only the index database — your files are never touched. Pass `--reindex` to rebuild the index from your files afterward (a plain reset leaves the index empty until the next reindex). Rebuilding may take time for large knowledge bases. --- ## Integration Tips ### With Obsidian 1. Open your `~/basic-memory` directory as an Obsidian vault 2. Use **Graph View** to visualize connections 3. Edit files directly in Obsidian 4. Changes sync automatically - ask the AI to read a note to see updates ![Obsidian graph view](https://docs.basicmemory.com/attachments/obsidian-coffee.png) Obsidian's graph view is excellent for discovering unexpected connections in your knowledge base. ### With Git Basic Memory files are git-friendly: ```bash cd ~/basic-memory git init git add . git commit -m "Initial knowledge base" ``` Benefits: - Version history for all changes - Backup to GitHub/GitLab - Collaborate with others - Track what changed over time ### With Other Editors Basic Memory uses standard Markdown that works with: - **VS Code** with Markdown extensions - **Typora** for rich text editing - **Any text editor** for quick edits - **Web editors** for remote access The database syncs regardless of how you edit files. --- ## Best Practices ### Knowledge Creation 1. **Create relations** - Link related concepts with `[[WikiLinks]]` 2. **Make observations** - Structure facts with `[category]` syntax 3. **Be descriptive** - Use clear titles and rich content 4. **Add context** - Include background and reasoning 5. **Review and refine** - Edit AI-generated content for accuracy ### Workflow 1. **Use special prompts** - "Continue conversation", "Recent activity", "Search" 2. **Build incrementally** - Add to existing notes rather than creating duplicates 3. **Organize regularly** - Move old content to archive 4. **Cross-reference** - Link new content to existing knowledge 5. **Use projects** - Separate work, personal, research ### Long-term Maintenance 1. **Archive old content** - Keep active knowledge base focused 2. **Refactor connections** - Update relations as knowledge evolves 3. **Regular reviews** - Periodically update key documents 4. **Backup regularly** - Use git, cloud sync, or snapshots --- ## Troubleshooting The two most common symptoms: - **Changes not showing up** — check `basic-memory status`, then rebuild the index with `basic-memory reindex` - **Claude can't find knowledge** — confirm the files are in the right project and the frontmatter is valid YAML For the full runbook — sync, search, install, config, and logs — see [Troubleshooting](https://docs.basicmemory.com/reference/troubleshooting). ### Getting Help - **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel - **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues) ```bash # View all commands basic-memory --help # Help for specific commands basic-memory status --help basic-memory project --help ``` --- ## Next Steps Learn the semantic patterns for observations and relations. All configuration options and environment variables. Complete command line tools reference. Visual knowledge navigation with graph view. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.