basicmachines-co/basic-memory

Без параметров.

• depthstring | integer | null

  How many relation hops to traverse (1-3 recommended for performance)

• max_relatedinteger

  Maximum total related results to return (default: 10, maximum: 100)

• output_formatenum

  Response format - "json" for structured JSON dict, "text" for compact markdown text

• pageinteger

  Page number of results to return (default: 1)

• page_sizeinteger

  Number of primary results to return per page (default: 10, maximum: 50)

• projectstring | null

  Project name to build context from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• timeframestring | null

  How far back to look. Supports natural language like "2 days ago", "last week"

• urlstringобязательный

  memory:// URI pointing to discussion content (e.g. memory://specs/search)

• output_formatenum

  "text" returns the existing human-readable result text. "json" returns structured project creation metadata.

• project_namestringобязательный

  Name for the new project (must be unique)

• project_pathstringобязательный

  File system path where the project will be stored

• set_defaultboolean

  Whether to set this project as the default (optional, defaults to False)

• workspacestring | null

  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).

• identifierstringобязательный

  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_directoryboolean

  If True, deletes an entire directory and all its contents. When True, identifier should be a directory path (without file extensions). Defaults to False.

• output_formatenum

  "text" preserves existing behavior (bool/string). "json" returns machine-readable deletion metadata.

• projectstring | null

  Project name to delete from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• delete_notesboolean

  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.

• project_namestringобязательный

  Name of the project to delete

• workspacestring | null

  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).

• contentstringобязательный

  The content to add or use for replacement

• expected_replacementsinteger | null

  For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match)

• find_textstring | null

  For find_replace operation - the text to find and replace

• identifierstringобязательный

  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.

• metadataobject | null

  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.

• operationenumобязательный

  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)

• output_formatenum

  "text" returns the existing markdown summary. "json" returns machine-readable edit metadata.

• projectstring | null

  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.

• project_idstring | null

  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().

• replace_subsectionsboolean | null

  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.

• sectionstring | null

  For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation")

• workspacestring | null

  Workspace slug, name, or tenant_id. When provided with project, routes as workspace/project. Cannot be combined with project_id.

• idstringобязательный

  Document identifier (permalink, title, or memory URL)

• depthinteger

  Recursion depth (1-10, default: 1 for immediate children only) Higher values show subdirectory contents recursively

• dir_namestring

  Directory path to list (default: root "/") Examples: "/", "/projects", "/research/ml"

• file_name_globstring | null

  Optional glob pattern for filtering file names Examples: ".md", "meeting", "project_"

• output_formatenum

  "text" for a readable listing or "json" for structured pagination data

• pageinteger

  One-indexed result page (default: 1)

• page_sizeinteger

  Number of nodes per page (default: 10, maximum: 200)

• projectstring | null

  Project name to list directory from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• sortenum | null

  Optional file ordering: "title_asc", "title_desc", "updated_asc", or "updated_desc". Directories remain first.

• output_formatenum

  "text" returns the existing human-readable project list. "json" returns structured project metadata.

• output_formatenum

  "text" returns human-readable workspace list. "json" returns structured workspace metadata.

• destination_folderstring | null

  Move the note into this folder, preserving the original filename. Mutually exclusive with destination_path. Only for single-file moves.

• destination_pathstring

  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.

• identifierstringобязательный

  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.

• is_directoryboolean

  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.

• output_formatenum

  "text" returns existing markdown guidance/success text. "json" returns machine-readable move metadata.

• projectstring | null

  Project name to move within. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• pathstringобязательный

  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)

• projectstring | null

  Project name to read from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• identifierstringобязательный

  The title or permalink of the note to read Can be a full memory:// URL, a permalink, a title, or search text

• include_frontmatterboolean

  When output_format="json", whether content should include the opening YAML frontmatter block.

• output_formatenum

  "text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter.

• pageinteger

  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_sizeinteger

  Number of fallback-search results per page (default: 10). When no match is found, this caps how many related-note suggestions are listed.

• projectstring | null

  Project name to read from. Optional - server will resolve using the hierarchy above. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• depthinteger

  How many relation hops to traverse (1-3 recommended)

• output_formatenum

  "text" returns human-readable summary text. "json" returns a flat list of recent items.

• pageinteger

  Page number for pagination (default 1)

• page_sizeinteger

  Number of items per page (default 10)

• projectstring | null

  Project name to query. Optional - server will resolve using the hierarchy above. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• timeframestring

  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"

• typestring | string[]

  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.

• note_typestringобязательный

  The note type to check for drift (e.g., "person").

• output_formatenum
• projectstring | null

  Project name. Optional -- server will resolve.

• project_idstring | null

  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().

• note_typestringобязательный

  The note type to analyze (e.g., "person", "meeting").

• output_formatenum
• projectstring | null

  Project name. Optional -- server will resolve.

• project_idstring | null

  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().

• thresholdnumber

  Minimum frequency (0-1) for a field to be suggested as optional. Default 0.25 (25%). Fields above 95% become required.

• identifierstring | null

  Specific note to validate (permalink, title, or path). If provided, validates only this note.

• note_typestring | null

  Note type to batch-validate (e.g., "person", "meeting"). If provided, validates all notes of this type.

• output_formatenum
• projectstring | null

  Project name. Optional -- server will resolve.

• project_idstring | null

  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().

• querystringобязательный

  Search query (full-text syntax supported by search_notes)

• after_datestring | null

  Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01")

• categoriesstring[] | null

  Optional list of observation categories for exact matching (e.g., ["requirement"]). Pair with entity_types=["observation"] to return only observations whose category matches exactly.

• entity_typesstring[] | null

  Optional list of entity types to filter by (e.g., ["entity", "observation"])

• metadata_filtersobject | null

  Optional structured frontmatter filters (e.g., {"status": "in-progress"})

• min_similaritynumber | null

  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.

• note_typesstring[] | null

  Optional list of note types to search (e.g., ["note", "person"])

• output_formatenum

  "text" preserves existing structured search response behavior. "json" returns a machine-readable dictionary payload.

• pageinteger

  The page number of results to return (default 1)

• page_sizeinteger

  The number of results to return per page (default 10)

• projectstring | null

  Project name to search in. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• querystring | null

  Optional search query string (supports boolean operators, phrases, patterns). Omit or pass None for filter-only searches using metadata_filters, tags, or status.

• search_all_projectsboolean

  Optional opt-in to search every accessible project. Ignored when project or project_id is supplied.

• search_typestring | null

  Type of search to perform, one of: "text", "title", "permalink", "vector", "semantic", "hybrid". Default is dynamic: "hybrid" when semantic search is enabled, otherwise "text".

• statusstring | null

  Optional status filter (frontmatter status); shorthand for metadata_filters["status"]

• tagsstring[] | null

  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.

• identifierstringобязательный

  The title or permalink of the note to view

• projectstring | null

  Project name to read from. Optional - server will resolve using hierarchy. If unknown, use list_memory_projects() to discover available projects.

• project_idstring | null

  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().

• contentstringобязательный

  Markdown content for the note, can include observations and relations

• directorystringобязательный

  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)

• metadataobject | null

  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.

• note_typestring

  Type of note to create (stored in frontmatter). Defaults to "note". Can be "guide", "report", "config", "person", etc.

• output_formatenum

  "text" returns the existing markdown summary. "json" returns machine-readable metadata.

• overwriteboolean | null

  If True, replace existing note on conflict. If False, error on conflict. If None (default), consult write_note_overwrite_default config setting.

• projectstring | null

  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.

• project_idstring | null

  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().

• tagsstring[] | string | null

  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")

• titlestringобязательный

  The title of the note

• workspacestring | null

  Workspace slug, name, or tenant_id. When provided with project, routes as workspace/project. Cannot be combined with project_id.