io.github.basicmachines-co/basic-memory

Return version, system, and configuration diagnostics for Basic Memory. Provides: - Basic Memory package version - Python version and platform details - Config file path and its contents (secrets redacted) Useful for troubleshooting installations and gathering information for support requests. Read-only; never emits secrets or API keys.

Search across all content in the knowledge base with comprehensive syntax support. This tool searches the knowledge base using full-text search, pattern matching, or exact permalink lookup. It supports filtering by content type, entity type, and date, with advanced boolean and phrase search capabilities. Project Resolution: Server resolves projects in this order: Single Project Mode → project parameter → default project. If project unknown, use list_memory_projects() or recent_activity() first. Set search_all_projects=True to search every accessible project; this is opt-in because it performs one search per project. ## Search Syntax Examples ### Basic Searches - `search_notes("my-project", "keyword")` - Find any content containing "keyword" - `search_notes("work-docs", "'exact phrase'")` - Search for exact phrase match ### Advanced Boolean Searches - `search_notes("my-project", "term1 term2")` - Strict implicit-AND first; retries with relaxed OR terms only if strict search returns no results - `search_notes("my-project", "term1 AND term2")` - Explicit AND search (both terms required) - `search_notes("my-project", "term1 OR term2")` - Either term can be present - `search_notes("my-project", "term1 NOT term2")` - Include term1 but exclude term2 - `search_notes("my-project", "(project OR planning) AND notes")` - Grouped boolean logic ### Content-Specific Searches - `search_notes("research", "tag:example")` - Search within specific tags (if supported by content) - `search_notes("work-project", "req", entity_types=["observation"], categories=["requirement"])` - Return only observations whose category is exactly "requirement" - `search_notes("team-docs", "author:username")` - Find content by author (if metadata available) **Note:** `tag:` shorthand is automatically converted to a `tags` filter, so it works with any search type (text, hybrid, vector). You can also use the `tags` parameter directly: `search_notes("project", "query", tags=["my-tag"])` ### Search Type Examples - `search_notes("my-project", "Meeting", search_type="title")` - Search only in titles - `search_notes("work-docs", "docs/meeting-*", search_type="permalink")` - Pattern match permalinks Note: Permalink patterns match the full path (e.g., "project/folder/chapter-13*", not just "chapter-13*"). - `search_notes("research", "keyword")` - Default search (hybrid when semantic is enabled, text when disabled) ### Filtering Options - `search_notes("my-project", "query", note_types=["note"])` - Search only notes - `search_notes("work-docs", "query", note_types=["note", "person"])` - Multiple note types - `search_notes("research", "query", entity_types=["observation"])` - Filter by entity type - `search_notes("research", "query", entity_types=["observation"], categories=["requirement"])` - Filter observations to an exact category - `search_notes("team-docs", "query", after_date="2024-01-01")` - Recent content only - `search_notes("my-project", "query", after_date="1 week")` - Relative date filtering - `search_notes("my-project", "query", tags=["security"])` - Filter by frontmatter tags - `search_notes("my-project", "query", status="in-progress")` - Filter by frontmatter status - `search_notes("my-project", "query", metadata_filters={"priority": {"$in": ["high"]}})` ### Structured Metadata Filters Filters are exact matches on frontmatter metadata. Supported forms: - Equality: `{"status": "in-progress"}` - Array contains (all): `{"tags": ["security", "oauth"]}` - Operators: - `$in`: `{"priority": {"$in": ["high", "critical"]}}` - `$gt`, `$gte`, `$lt`, `$lte`: `{"schema.confidence": {"$gt": 0.7}}` - `$between`: `{"schema.confidence": {"$between": [0.3, 0.6]}}` - Nested keys use dot notation (e.g., `"schema.confidence"`). ### Filter-only Searches Omit `query` (or pass None) when only using structured filters: - `search_notes(metadata_filters={"type": "spec"}, project="my-project")` - `search_notes(tags=["security"], project="my-project")` - `search_notes(status="draft", project="my-project")` ### Convenience Filters `tags` and `status` are shorthand for metadata_filters. If the same key exists in metadata_filters, that value wins. ### Advanced Pattern Examples - `search_notes("work-project", "project AND (meeting OR discussion)")` - Complex boolean logic - `search_notes("research", ""exact phrase" AND keyword")` - Combine phrase and keyword search - `search_notes("dev-notes", "bug NOT fixed")` - Exclude resolved issues - `search_notes("archive", "docs/2024-*", search_type="permalink")` - Year-based permalink search Args: query: Optional search query string (supports boolean operators, phrases, patterns). Omit or pass None for filter-only searches using metadata_filters, tags, or status. project: Project name to search in. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). search_all_projects: Optional opt-in to search every accessible project. Ignored when `project` or `project_id` is supplied. page: The page number of results to return (default 1) page_size: The number of results to return per page (default 10) search_type: Type of search to perform, one of: "text", "title", "permalink", "vector", "semantic", "hybrid". Default is dynamic: "hybrid" when semantic search is enabled, otherwise "text". output_format: "text" preserves existing structured search response behavior. "json" returns a machine-readable dictionary payload. note_types: Optional list of note types to search (e.g., ["note", "person"]) entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"]) categories: Optional list of observation categories for exact matching (e.g., ["requirement"]). Pair with entity_types=["observation"] to return only observations whose category matches exactly. after_date: Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01") metadata_filters: Optional structured frontmatter filters (e.g., {"status": "in-progress"}) tags: Optional tag filter (frontmatter tags); shorthand for metadata_filters["tags"]. Accepts a list (["a", "b"]) or a comma-separated string ("a,b"), matching the write_note tags convention and the tag: query shorthand. status: Optional status filter (frontmatter status); shorthand for metadata_filters["status"] min_similarity: Optional float to override the global semantic_min_similarity threshold for this query. E.g., 0.0 to see all vector results, or 0.8 for high precision. Only applies to vector and hybrid search types. context: Optional FastMCP context for performance caching. Returns: Formatted markdown text (output_format="text"), dict (output_format="json"), or helpful error guidance string if search fails Pagination note: use `total` as a count only when `total_is_exact` is true. Vector and hybrid searches skip the count query (it would cost a second semantic retrieval pass), report `total: 0` with `total_is_exact: false`, and use `has_more` for pagination. Examples: # Basic text search results = await search_notes("project planning") # Plain multi-term text uses strict matching first, then relaxed OR fallback if needed # Boolean AND search (both terms must be present) results = await search_notes("project AND planning") # Boolean OR search (either term can be present) results = await search_notes("project OR meeting") # Boolean NOT search (exclude terms) results = await search_notes("project NOT meeting") # Boolean search with grouping results = await search_notes("(project OR planning) AND notes") # Exact phrase search results = await search_notes(""weekly standup meeting"") # Search with note type filter - type property in frontmatter results = await search_notes( "meeting notes", note_types=["note"], ) # Search with entity type filter results = await search_notes( "meeting notes", entity_types=["observation"], ) # Search for recent content results = await search_notes( "bug report", after_date="1 week" ) # Pattern matching on permalinks results = await search_notes( "docs/meeting-*", search_type="permalink" ) # Title-only search results = await search_notes( "Machine Learning", search_type="title" ) # Complex search with multiple filters results = await search_notes( "(bug OR issue) AND NOT resolved", note_types=["note"], after_date="2024-01-01" ) # Explicit project specification results = await search_notes("project planning", project="my-project")

Read a file's raw content by path or permalink. This tool provides direct access to file content in the knowledge base, handling different file types appropriately. Uses stateless architecture - project parameter optional with server resolution. Supported file types: - Text files (markdown, code, etc.) are returned as plain text - Images are automatically resized/optimized for display - Other binary files are returned as base64 if below size limits Args: path: The path or permalink to the file. Can be: - A regular file path (docs/example.md) - A memory URL (memory://docs/example) - A permalink (docs/example) project: Project name to read from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: A dictionary with the file content and metadata: - For text: {"type": "text", "text": "content", "content_type": "text/markdown", "encoding": "utf-8"} - For images: {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "base64_data"}} - For other files: {"type": "document", "source": {"type": "base64", "media_type": "content_type", "data": "base64_data"}} - For errors: {"type": "error", "error": "error message"} Examples: # Read a markdown file result = await read_content("docs/project-specs.md") # Read an image image_data = await read_content("assets/diagram.png") # Read using memory URL content = await read_content("memory://docs/architecture") # Read configuration file config = await read_content("config/settings.json") # Explicit project specification result = await read_content("docs/project-specs.md", project="my-project") Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If path attempts path traversal

Get recent activity for a specific project or across all projects. Project Resolution: The server resolves projects in this order: 1. Single Project Mode - server constrained to one project, parameter ignored 2. Explicit project parameter - specify which project to query 3. Default project - server configured default if no project specified Discovery Mode: When no specific project can be resolved, returns activity across all projects to help discover available projects and their recent activity. Project Discovery (when project is unknown): 1. Call list_memory_projects() to see available projects 2. Or use this tool without project parameter to see cross-project activity 3. Ask the user which project to focus on 4. Remember their choice for the conversation Args: type: Filter by content type(s). Can be a string or list of strings. Valid options: - "entity" or ["entity"] for knowledge entities - "relation" or ["relation"] for connections between entities - "observation" or ["observation"] for notes and observations Multiple types can be combined: ["entity", "relation"] Case-insensitive: "ENTITY" and "entity" are treated the same. Default is entity-only. Specify other types explicitly to include observations and relations. depth: How many relation hops to traverse (1-3 recommended) page: Page number for pagination (default 1) page_size: Number of items per page (default 10) timeframe: Time window to search. Supports natural language: - Relative: "2 days ago", "last week", "yesterday" - Points in time: "2024-01-01", "January 1st" - Standard format: "7d", "24h" project: Project name to query. Optional - server will resolve using the hierarchy above. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). output_format: "text" returns human-readable summary text. "json" returns a flat list of recent items. context: Optional FastMCP context for performance caching. Returns: Human-readable summary of recent activity. When no specific project is resolved, returns cross-project discovery information. When a specific project is resolved, returns detailed activity for that project. Examples: # Cross-project discovery mode recent_activity() recent_activity(timeframe="yesterday") # Project-specific activity recent_activity(project="work-docs", type="entity", timeframe="yesterday") recent_activity(project="research", type=["entity", "relation"], timeframe="today") recent_activity(project="notes", type="entity", depth=2, timeframe="2 weeks ago") Raises: ToolError: If project doesn't exist or type parameter contains invalid values Notes: - Higher depth values (>3) may impact performance with large result sets - For focused queries, consider using build_context with a specific URI - Max timeframe is 1 year in the past

Write a markdown note to the knowledge base. Creates a markdown note with semantic observations and relations. If the note already exists, returns an error by default. Pass overwrite=True to replace the existing note. For incremental updates, use edit_note instead. Project Resolution: Server resolves projects using a unified priority chain (same in local and cloud modes): Single Project Mode → project parameter → default project. Uses default project automatically. Specify `project` parameter to target a different project. The content can include semantic observations and relations using markdown syntax: Observations format: `- [category] Observation text #tag1 #tag2 (optional context)` Examples: `- [design] Files are the source of truth #architecture (All state comes from files)` `- [tech] Using SQLite for storage #implementation` `- [note] Need to add error handling #todo` Relations format: - Explicit: `- relation_type [[Entity]] (optional context)` - Quoted: `- "multi word relation type" [[Entity]] (optional context)` - Quoted: `- 'multi word relation type' [[Entity]] (optional context)` - Disambiguation: Add `#bm:links_to` when prose before `[[Entity]]` must not be treated as a single-token relation type - Inline: Any other `[[Entity]]` reference creates a `links_to` relation Examples: `- depends_on [[Content Parser]] (Need for semantic extraction)` `- "based on" [[Design Notes]]` `- 'in response to' [[Incident Review]]` `- Mother [[Alice]] #bm:links_to` `- implements [[Search Spec]] (Initial implementation)` `- This feature extends [[Base Design]] and uses [[Core Utils]]` Args: title: The title of the note content: Markdown content for the note, can include observations and relations directory: Directory path relative to project root where the file should be saved. Use forward slashes (/) as separators. Use "/" or "" to write to project root. Examples: "notes", "projects/2025", "research/ml", "/" (root) project: Project name to write to. Optional - server will resolve using the hierarchy above. Use "workspace/project" to route to a project in a specific cloud workspace. A bare name that exists in multiple workspaces resolves to the default workspace, so use the qualified form (or project_id) to disambiguate. If unknown, use list_memory_projects() to discover available projects and their qualified names. workspace: Workspace slug, name, or tenant_id. When provided with `project`, routes as `workspace/project`. Cannot be combined with `project_id`. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None. Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3") note_type: Type of note to create (stored in frontmatter). Defaults to "note". Can be "guide", "report", "config", "person", etc. metadata: Optional dict of extra frontmatter fields merged into entity_metadata. Useful for schema notes or any note that needs custom YAML frontmatter beyond title/type/tags. Nested dicts are supported. overwrite: If True, replace existing note on conflict. If False, error on conflict. If None (default), consult write_note_overwrite_default config setting. output_format: "text" returns the existing markdown summary. "json" returns machine-readable metadata. context: Optional FastMCP context for performance caching. Returns: A markdown formatted summary of the semantic content, including: - Creation/update status with project name - File path and checksum - Observation counts by category - Relation counts (resolved/unresolved) - Tags if present - Session tracking metadata for project awareness Examples: # Create a simple note (uses default project automatically) write_note( project="my-research", title="Meeting Notes", directory="meetings", content="# Weekly Standup\n\n- [decision] Use SQLite for storage #tech" ) # Create a note with tags and note type write_note( project="work-project", title="API Design", directory="specs", content="# REST API Specification\n\n- implements [[Authentication]]", tags=["api", "design"], note_type="guide" ) # Overwrite an existing note explicitly write_note( project="my-research", title="Meeting Notes", directory="meetings", content="# Weekly Standup\n\n- [decision] Use PostgreSQL instead #tech", overwrite=True ) # Create a schema note with custom frontmatter via metadata write_note( title="Person", directory="schemas", note_type="schema", content="# Person\n\nSchema for person entities.", metadata={ "entity": "person", "version": 1, "schema": {"name": "string", "role?": "string"}, "settings": {"validation": "warn"}, }, ) Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If directory path attempts path traversal

View a markdown note as a formatted artifact. This tool reads a note using the same logic as read_note but instructs Claude to display the content as a markdown artifact in the Claude Desktop app. Project parameter optional with server resolution. Args: identifier: The title or permalink of the note to view project: Project name to read from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: Instructions for Claude to create a markdown artifact with the note content. Examples: # View a note by title view_note("Meeting Notes") # View a note by permalink view_note("meetings/weekly-standup") # Explicit project specification view_note("Meeting Notes", project="my-project") Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If identifier attempts path traversal

Edit an existing markdown note in the knowledge base. Makes targeted changes to existing notes without rewriting the entire content. Project Resolution: Server resolves projects in this order: Single Project Mode → project parameter → default project. If project unknown, use list_memory_projects() or recent_activity() first. Args: identifier: The exact title, permalink, or memory:// URL of the note to edit. Must be an exact match - fuzzy matching is not supported for edit operations. Use search_notes() or read_note() first to find the correct identifier if uncertain. operation: The editing operation to perform: - "append": Add content to the end of the note (creates the note if it doesn't exist) - "prepend": Add content to the beginning of the note (creates the note if it doesn't exist) - "find_replace": Replace occurrences of find_text with content (note must exist) - "replace_section": Replace a markdown section identified by its header (note must exist). By default the section spans through the next heading of the same or higher level, so its subsections are replaced too; see replace_subsections. - "insert_before_section": Insert content before a section heading without consuming it (note must exist) - "insert_after_section": Insert content after a section heading without consuming it (note must exist) content: The content to add or use for replacement project: Project name to edit in. Optional - server will resolve using hierarchy. Use "workspace/project" to route to a project in a specific cloud workspace. If unknown, use list_memory_projects() to discover available projects. workspace: Workspace slug, name, or tenant_id. When provided with `project`, routes as `workspace/project`. Cannot be combined with `project_id`. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation") find_text: For find_replace operation - the text to find and replace expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match) replace_subsections: For replace_section operation. Default (true): the section spans everything through the next heading of the same or higher level in the original note, so replacing "## Section" also replaces its "###" subsections — the replacement content may freely introduce new headings. Set to false to replace only the immediate content under the header, stopping at the next heading of any level and preserving subsections. metadata: Optional dict of frontmatter fields to merge, independent of `operation`. Provided keys overwrite existing frontmatter values (or are added if new); unrelated frontmatter keys and the note body are left untouched. Can be combined with any operation in the same call. `title`, `type`, and `permalink` are ignored since those have their own dedicated handling. Key deletion is not supported. output_format: "text" returns the existing markdown summary. "json" returns machine-readable edit metadata. context: Optional FastMCP context for performance caching. Returns: A markdown formatted summary of the edit operation and resulting semantic content, including operation details, file path, observations, relations, and project metadata. Examples: # Add new content to end of note edit_note("my-project", "project-planning", "append", "\n## New Requirements\n- Feature X\n- Feature Y") # Add timestamp at beginning (frontmatter-aware) edit_note("work-docs", "meeting-notes", "prepend", "## 2025-05-25 Update\n- Progress update...\n\n") # Update version number (single occurrence) edit_note("api-project", "config-spec", "find_replace", "v0.13.0", find_text="v0.12.0") # Update version in multiple places with validation edit_note("docs-project", "api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3) # Replace text that appears multiple times - validate count first edit_note("team-docs", "docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5) # Replace implementation section (subsections under it are replaced too) edit_note("specs", "api-spec", "replace_section", "New implementation approach...\n", section="## Implementation") # Replace only the intro text under a header, keeping its subsections edit_note("specs", "api-spec", "replace_section", "New intro...\n", section="## Implementation", replace_subsections=False) # Replace subsection with more specific header edit_note("docs", "docs/setup", "replace_section", "Updated install steps\n", section="### Installation") # Using different identifier formats (must be exact matches) edit_note("work-project", "Meeting Notes", "append", "\n- Follow up on action items") # exact title edit_note("work-project", "docs/meeting-notes", "append", "\n- Follow up tasks") # exact permalink # If uncertain about identifier, search first: # search_notes("work-project", "meeting") # Find available notes # edit_note("work-project", "docs/meeting-notes-2025", "append", "content") # Use exact result # Add new section to document edit_note("planning", "project-plan", "replace_section", "TBD - needs research\n", section="## Future Work") # Update status across document (expecting exactly 2 occurrences) edit_note("reports", "status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2) # Update frontmatter fields without touching the body (any operation works; # append with empty content is a no-op on the body itself) edit_note("support", "tickets/2026-06-18-printer-offline", "append", "", metadata={"status": "resolved", "closed_at": "2026-06-18T10:42:00Z"}) Raises: HTTPError: If project doesn't exist or is inaccessible ValueError: If operation is invalid or required parameters are missing SecurityError: If identifier attempts path traversal Note: Edit operations require exact identifier matches. If unsure, use read_note() or search_notes() first to find the correct identifier. When the identifier looks like a file path and the file exists on disk but is not indexed yet, edit_note indexes that file automatically and retries the edit. The tool provides detailed error messages with suggestions if operations fail.

Delete a note or directory from the knowledge base. Permanently removes a note or directory from the specified project. For single notes, they are identified by title or permalink. For directories, use is_directory=True and provide the directory path. If the note/directory doesn't exist, the operation returns False without error. If deletion fails, helpful error messages are provided. Project Resolution: Server resolves projects in this order: Single Project Mode → project parameter → default project. If project unknown, use list_memory_projects() or recent_activity() first. Args: identifier: For files: note title or permalink to delete. For directories: the directory path (e.g., "docs", "projects/2025"). Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes" is_directory: If True, deletes an entire directory and all its contents. When True, identifier should be a directory path (without file extensions). Defaults to False. project: Project name to delete from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). output_format: "text" preserves existing behavior (bool/string). "json" returns machine-readable deletion metadata. context: Optional FastMCP context for performance caching. Returns: True if note was successfully deleted, False if note was not found. For directories, returns a formatted summary of deleted files. On errors, returns a formatted string with helpful troubleshooting guidance. Examples: # Delete by title delete_note("Meeting Notes: Project Planning") # Delete by permalink delete_note("notes/project-planning") # Delete with explicit project delete_note("experiments/ml-model-results", project="research") # Delete entire directory delete_note("docs", is_directory=True) # Delete nested directory delete_note("projects/2024", is_directory=True) # Common usage pattern if delete_note("old-draft"): print("Note deleted successfully") else: print("Note not found or already deleted") Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If identifier attempts path traversal Warning: This operation is permanent and cannot be undone. The note/directory files will be removed from the filesystem and all references will be lost. Note: If the note is not found, this function provides helpful error messages with suggestions for finding the correct identifier, including search commands and alternative formats to try.

Return the raw markdown for a note, or guidance text if no match is found. Finds and retrieves a note by its title, permalink, or content search, returning the raw markdown content including observations, relations, and metadata. Project Resolution: Server resolves projects using a unified priority chain (same in local and cloud modes): Single Project Mode → project parameter → default project. Uses default project automatically. Specify `project` parameter to target a different project. This tool will try multiple lookup strategies to find the most relevant note: 1. Direct permalink lookup 2. Title search fallback 3. Text search as last resort Args: project: Project name to read from. Optional - server will resolve using the hierarchy above. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). identifier: The title or permalink of the note to read Can be a full memory:// URL, a permalink, a title, or search text page: Page of fallback-search results to use when the identifier does not resolve to a note directly (default: 1). A direct or exact-title match always returns the full note content — page/page_size never chunk the note itself, and the title-match lookup pages through fixed-size pages of title results until an exact match is found or results are exhausted, regardless of page or page_size. page_size: Number of fallback-search results per page (default: 10). When no match is found, this caps how many related-note suggestions are listed. output_format: "text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter. include_frontmatter: When output_format="json", whether content should include the opening YAML frontmatter block. context: Optional FastMCP context for performance caching. Returns: The full markdown content of the note if found, or helpful guidance if not found. Content includes frontmatter, observations, relations, and all markdown formatting. Examples: # Read by permalink read_note("my-research", "specs/search-spec") # Read by title read_note("work-project", "Search Specification") # Read with memory URL read_note("my-research", "memory://specs/search-spec") # Read recent meeting notes read_note("team-docs", "Weekly Standup") # Page through fallback-search suggestions when nothing matches directly read_note("unknown topic", page=2, page_size=5) Raises: HTTPError: If project doesn't exist or is inaccessible SecurityError: If identifier attempts path traversal Note: If the exact note isn't found, this tool provides helpful suggestions including related notes, search commands, and note creation templates.

Move a note or directory to a new location within the same project. Moves a note or directory from one location to another within the project, updating all database references and maintaining semantic content. Uses stateless architecture - project parameter optional with server resolution. Args: identifier: For files: exact entity identifier (title, permalink, or memory:// URL). For directories: the directory path (e.g., "docs", "projects/2025"). Must be an exact match - fuzzy matching is not supported for move operations. Use search_notes() or list_directory() first to find the correct path if uncertain. destination_path: For files: new path relative to project root (e.g., "work/meetings/note.md") For directories: new directory path (e.g., "archive/docs") Mutually exclusive with destination_folder. destination_folder: Move the note into this folder, preserving the original filename. Mutually exclusive with destination_path. Only for single-file moves. is_directory: If True, moves an entire directory and all its contents. When True, identifier and destination_path should be directory paths (without file extensions). Defaults to False. project: Project name to move within. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). output_format: "text" returns existing markdown guidance/success text. "json" returns machine-readable move metadata. context: Optional FastMCP context for performance caching. Returns: Success message with move details and project information. For directories, includes count of files moved and any errors. Examples: # Move a single note to new folder (exact title match) move_note("My Note", "work/notes/my-note.md") # Move by exact permalink move_note("my-note-permalink", "archive/old-notes/my-note.md") # Move note to archive folder (filename preserved automatically) move_note("my-note", destination_folder="archive") # Move with complex path structure move_note("experiments/ml-results", "archive/2025/ml-experiments.md") # Explicit project specification move_note("My Note", "work/notes/my-note.md", project="work-project") # Move entire directory move_note("docs", "archive/docs", is_directory=True) # Move nested directory move_note("projects/2024", "archive/projects/2024", is_directory=True) # If uncertain about identifier, search first: # search_notes("my note") # Find available notes # move_note("docs/my-note-2025", "archive/my-note.md") # Use exact result Raises: ToolError: If project doesn't exist, identifier is not found, or destination_path is invalid Note: This operation moves notes within the specified project only. Moving notes between different projects is not currently supported. The move operation: - Updates the entity's file_path in the database - Moves the physical file on the filesystem - Optionally updates permalinks if configured - Re-indexes the entity for search - Maintains all observations and relations

List all available projects with their status. Shows projects from both local and cloud sources when cloud credentials are available, merging by permalink to give a unified view. Each project entry includes an `external_id` (UUID). Pass that value as the `project_id` parameter on other tools to address a specific project unambiguously across cloud workspaces — useful when the same project name exists in more than one workspace. Args: output_format: "text" returns the existing human-readable project list. "json" returns structured project metadata. context: Optional FastMCP context for progress/status logging.

Create a new Basic Memory project. Creates a new project with the specified name and path. The project directory will be created if it doesn't exist. Optionally sets the new project as default. Args: project_name: Name for the new project (must be unique) project_path: File system path where the project will be stored set_default: Whether to set this project as the default (optional, defaults to False) workspace: Optional cloud workspace selector to create the project in. Slug is preferred for AI callers, but tenant_id and unique name are also accepted. When omitted, the connection's default workspace is used. Discover values via `list_workspaces`. A workspace selector implies cloud routing: without cloud credentials the call fails fast instead of silently creating a local project (#954). output_format: "text" returns the existing human-readable result text. "json" returns structured project creation metadata. context: Optional FastMCP context for progress/status logging. Returns: Confirmation message with project details Example: create_memory_project("my-research", "~/Documents/research") create_memory_project("work-notes", "/home/user/work", set_default=True) create_memory_project("team-notes", "/team/notes", workspace="team-paul")

Delete a Basic Memory project. Removes a project from Basic Memory's configuration and database records. By default the project's note files are retained: local projects keep their files on disk, cloud projects keep their files in cloud storage. Pass delete_notes=True to also delete the note files themselves. Args: project_name: Name of the project to delete delete_notes: Also delete the project's note files (from local disk for local projects, from cloud storage for cloud projects). Defaults to False, which only stops tracking the project. workspace: Optional cloud workspace selector to delete the project from. Slug is preferred for AI callers, but tenant_id and unique name are also accepted. When omitted, the connection's default workspace is used. A workspace selector implies cloud routing: without cloud credentials the call fails fast, matching create_memory_project behavior (#954). Returns: Confirmation message describing what was deleted and whether note files were removed or retained. Example: delete_project("old-project") delete_project("old-project", delete_notes=True) delete_project("team-project", workspace="team-paul") Warning: This action cannot be undone. With delete_notes=False the project must be re-added to access its content through Basic Memory again; with delete_notes=True the note files themselves are permanently deleted.

Return a search results UI as an embedded MCP-UI resource.

Return a note preview UI as an embedded MCP-UI resource.

ChatGPT/OpenAI MCP search adapter returning a single text content item. Args: query: Search query (full-text syntax supported by `search_notes`) context: Optional FastMCP context passed through for auth/session data Returns: List with one dict: `{ "type": "text", "text": "{...JSON...}" }` where the JSON body contains `results`, `total_count`, and echo of `query`.

ChatGPT/OpenAI MCP fetch adapter returning a single text content item. Args: id: Document identifier (permalink, title, or memory URL) context: Optional FastMCP context passed through for auth/session data Returns: List with one dict: `{ "type": "text", "text": "{...JSON...}" }` where the JSON body includes `id`, `title`, `text`, `url`, and metadata.

List workspaces available to the current cloud user. Args: output_format: "text" returns human-readable workspace list. "json" returns structured workspace metadata. context: Optional FastMCP context for progress/status logging.

List directory contents from the knowledge base with optional filtering. This tool provides 'ls' functionality for browsing the knowledge base directory structure. It can list immediate children or recursively explore subdirectories with depth control, and supports glob pattern filtering for finding specific files. Args: dir_name: Directory path to list (default: root "/") Examples: "/", "/projects", "/research/ml" depth: Recursion depth (1-10, default: 1 for immediate children only) Higher values show subdirectory contents recursively file_name_glob: Optional glob pattern for filtering file names Examples: "*.md", "*meeting*", "project_*" sort: Optional file ordering: "title_asc", "title_desc", "updated_asc", or "updated_desc". Directories remain first. page: One-indexed result page (default: 1) page_size: Number of nodes per page (default: 10, maximum: 200) output_format: "text" for a readable listing or "json" for structured pagination data project: Project name to list directory from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: Formatted listing of directory contents with file metadata Examples: # List root directory contents list_directory() # List specific folder list_directory(dir_name="/projects") # Find all markdown files list_directory(file_name_glob="*.md") # Deep exploration of research folder list_directory(dir_name="/research", depth=3) # Find meeting notes in projects folder list_directory(dir_name="/projects", file_name_glob="*meeting*") # Continue a large listing list_directory(dir_name="/projects", page=2, page_size=10) # List folders first, then notes from newest to oldest list_directory(dir_name="/projects", sort="updated_desc") # Explicit project specification list_directory(project="work-docs", dir_name="/projects") Raises: ToolError: If project doesn't exist or directory path is invalid

Validate notes against their resolved schema. Validates a specific note (by identifier), all notes of a given type, or — when called with neither — all notes of every type that has a schema defined, with a per-type breakdown. Returns warnings/errors based on the schema's validation mode. Schemas are resolved in priority order: 1. Inline schema (dict in frontmatter) 2. Explicit reference (string in frontmatter) 3. Implicit by type (type field matches schema note's entity field) 4. No schema (no validation) Project Resolution: Server resolves projects in this order: Single Project Mode -> project parameter -> default. If project unknown, use list_memory_projects() first. Args: note_type: Note type to batch-validate (e.g., "person", "meeting"). If provided, validates all notes of this type. identifier: Specific note to validate (permalink, title, or path). If provided, validates only this note. project: Project name. Optional -- server will resolve. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: ValidationReport with per-note results, or error guidance string Examples: # Validate all person notes schema_validate(note_type="person") # Validate a specific note schema_validate(identifier="people/paul-graham") # Validate every type that has a schema defined schema_validate() # Validate in a specific project schema_validate(note_type="person", project="my-research")

Analyze existing notes and suggest a schema definition. Examines observation categories and relation types across all notes of the given type. Returns frequency analysis and suggested Picoschema YAML that can be saved as a schema note. Frequency thresholds: - 95%+ present -> required field - threshold+ present -> optional field - Below threshold -> excluded (but noted) Project Resolution: Server resolves projects in this order: Single Project Mode -> project parameter -> default. If project unknown, use list_memory_projects() first. Args: note_type: The note type to analyze (e.g., "person", "meeting"). threshold: Minimum frequency (0-1) for a field to be suggested as optional. Default 0.25 (25%). Fields above 95% become required. project: Project name. Optional -- server will resolve. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: InferenceReport with frequency data and suggested schema, or error string Examples: # Infer schema for person notes schema_infer("person") # Use a higher threshold (50% minimum) schema_infer("meeting", threshold=0.5) # Infer in a specific project schema_infer("person", project="my-research")

Detect drift between a schema definition and actual note usage. Compares the existing schema for a note type against how notes of that type are actually structured. Identifies new fields that have appeared, declared fields that are rarely used, and cardinality changes (single-value vs array). Useful for evolving schemas as your knowledge base grows -- run periodically to see if your schema still matches reality. Project Resolution: Server resolves projects in this order: Single Project Mode -> project parameter -> default. If project unknown, use list_memory_projects() first. Args: note_type: The note type to check for drift (e.g., "person"). project: Project name. Optional -- server will resolve. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). context: Optional FastMCP context for performance caching. Returns: DriftReport with new fields, dropped fields, and cardinality changes, or error guidance string Examples: # Check drift for person schema schema_diff("person") # Check drift in a specific project schema_diff("person", project="my-research")

Get context needed to continue a discussion within a specific project. This tool enables natural continuation of discussions by loading relevant context from memory:// URIs. It uses pattern matching to find relevant content and builds a rich context graph of related information. Project Resolution: Server resolves projects using a unified priority chain (same in local and cloud modes): Single Project Mode → project parameter → default project. Uses default project automatically. Specify `project` parameter to target a different project. Args: project: Project name to build context from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects. project_id: Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects(). url: memory:// URI pointing to discussion content (e.g. memory://specs/search) depth: How many relation hops to traverse (1-3 recommended for performance) timeframe: How far back to look. Supports natural language like "2 days ago", "last week" page: Page number of results to return (default: 1) page_size: Number of primary results to return per page (default: 10, maximum: 50) max_related: Maximum total related results to return (default: 10, maximum: 100) output_format: Response format - "json" for structured JSON dict, "text" for compact markdown text context: Optional FastMCP context for performance caching. Returns: dict (output_format="json"): Structured JSON with internal fields excluded str (output_format="text"): Compact markdown representation Examples: # Continue a specific discussion build_context("my-project", "memory://specs/search") # Get deeper context about a component build_context("work-docs", "memory://components/memory-service", depth=2) # Get text output for compact context build_context("research", "memory://specs/search", output_format="text") Raises: ToolError: If project doesn't exist or depth parameter is invalid