Skip to main content

​
list_memory_projects

List all available projects with their status. 
async def list_memory_projects(
    output_format: Literal["text", "json"] = "text",
    workspace: str | None = None,
    context: Context | None = None,
) -> str | dict

​
Parameters

​
output_format
string
default:"text"
Response format:
  • text - Human-readable project list with guidance
  • json - Structured project metadata
​
workspace
string
Cloud workspace name or tenant_id. Falls back to config.default_workspace when not specified.

​
Returns

​
result
string | dict
Text format:
  • List of available projects with source (local, cloud, local+cloud)
  • Guidance for selecting a project
  • Session reminder to track selected project
JSON format:
{
  "projects": [
    {
      "name": "project-name",
      "path": "/path/to/project",
      "local_path": "/local/path",
      "cloud_path": "/cloud/path",
      "source": "local+cloud",
      "is_default": true,
      "is_private": false,
      "display_name": "Project Display Name",
      "workspace_name": "workspace",
      "workspace_type": "personal",
      "workspace_tenant_id": "tenant-id"
    }
  ],
  "default_project": "project-name",
  "constrained_project": null
}
Constrained Mode: When BASIC_MEMORY_MCP_PROJECT is set, shows single project constraint info.

​
Project Sources

Projects can have different sources:
  • local - Only exists in local configuration
  • cloud - Only exists in cloud workspace
  • local+cloud - Exists in both local and cloud

​
Examples

# List all projects (text)
list_memory_projects()

# Get structured project data
list_memory_projects(output_format="json")

# List projects in specific workspace
list_memory_projects(workspace="workspace-tenant-id")

​
create_memory_project

Create a new Basic Memory project. 
async def create_memory_project(
    project_name: str,
    project_path: str,
    set_default: bool = False,
    output_format: Literal["text", "json"] = "text",
    context: Context | None = None,
) -> str | dict

​
Parameters

​
project_name
string
required
Name for the new project (must be unique)
​
project_path
string
required
File system path where the project will be stored. The project directory will be created if it doesn’t exist.
​
set_default
boolean
default:"false"
Whether to set this project as the default project
​
output_format
string
default:"text"
Response format:
  • text - Human-readable confirmation
  • json - Structured project creation metadata

​
Returns

​
result
string | dict
Text format:
  • Confirmation message
  • Project details (name, path, default status)
  • Usage guidance
JSON format:
{
  "name": "project-name",
  "path": "/path/to/project",
  "is_default": false,
  "created": true,
  "already_exists": false
}
Error cases:
  • If project already exists: already_exists: true, created: false
  • If constrained mode: error: "PROJECT_CONSTRAINED"

​
Examples

# Create basic project
create_memory_project(
    "my-research",
    "~/Documents/research"
)

# Create and set as default
create_memory_project(
    "work-notes",
    "/home/user/work",
    set_default=True
)

# Get structured response
create_memory_project(
    "team-docs",
    "~/team-docs",
    output_format="json"
)

​
Constraints

  • Cannot create projects when BASIC_MEMORY_MCP_PROJECT is set (constrained mode)
  • Project names must be unique
  • Project path will be created if it doesn’t exist

​
delete_project

Delete a Basic Memory project. 
async def delete_project(
    project_name: str,
    context: Context | None = None,
) -> str

​
Parameters

​
project_name
string
required
Name of the project to delete

​
Returns

​
result
string
Confirmation message about project deletion including:
  • Removed project details (name, path)
  • Note that files remain on disk
  • Instructions for re-adding if needed

​
Examples

# Delete a project
delete_project("old-project")

​
Important Notes

  • This does NOT delete files on disk - only removes the project from Basic Memory’s configuration and database
  • The project will need to be re-added to access its content through Basic Memory again
  • Cannot delete projects when BASIC_MEMORY_MCP_PROJECT is set (constrained mode)
  • This action cannot be undone

​
Constraints

  • Cannot delete projects in constrained mode
  • Project must exist (raises error if not found)
  • Shows list of available projects if project name doesn’t match

​
get_current_project

Get information about the currently active project. 
async def get_current_project(
    project: Optional[str] = None,
    context: Context | None = None,
) -> dict

​
Parameters

​
project
string
Optional project name to query. If not provided, uses default project resolution.

​
Returns

​
result
dict
Project information including:
{
  "name": "project-name",
  "path": "/path/to/project",
  "external_id": "uuid",
  "is_default": true,
  "mode": "local",
  "home": "/resolved/path"
}

​
Examples

# Get current/default project
get_current_project()

# Get specific project info
get_current_project(project="work-docs")

​
list_workspaces

List available cloud workspaces (tenant_id, type, role, and name). 
async def list_workspaces(
    output_format: Literal["text", "json"] = "text",
    context: Context | None = None,
) -> str | dict

​
Parameters

​
output_format
string
default:"text"
Response format:
  • text - Human-readable workspace list
  • json - Structured workspace metadata

​
Returns

​
result
string | dict
Text format:
  • List of available workspaces with tenant_id, type, and role
  • Usage guidance for workspace parameter
JSON format:
{
  "workspaces": [
    {
      "tenant_id": "tenant-uuid",
      "name": "workspace-name",
      "workspace_type": "personal",
      "role": "owner",
      "organization_id": "org-uuid",
      "has_active_subscription": true
    }
  ],
  "count": 1
}

​
Workspace Types

  • personal - Individual user workspace
  • organization - Organization workspace with multiple members

​
Workspace Roles

  • owner - Full control over workspace
  • admin - Administrative access
  • member - Standard access

​
Examples

# List all workspaces (text)
list_workspaces()

# Get structured workspace data
list_workspaces(output_format="json")

​
Use Cases

  • Discover available cloud workspaces for current user
  • Find workspace tenant_id for use in other tools
  • Check subscription status for workspaces
  • Verify workspace access and role

​
cloud_info

Return optional Basic Memory Cloud information and setup guidance. 
def cloud_info() -> str

​
Returns

​
result
string
Markdown-formatted content with:
  • Cloud features overview
  • Setup instructions
  • Subscription information
  • Getting started guide

​
Examples

# Get cloud information
cloud_info()

​
Use Cases

  • Learn about cloud features
  • Get setup instructions
  • Understand subscription tiers
  • Find cloud getting started guide
This is a discovery tool - no parameters required. Content is loaded from static resource file.

​
release_notes

Return the latest product release notes for optional user review. 
def release_notes() -> str

​
Returns

​
result
string
Markdown-formatted release notes including:
  • New features
  • Bug fixes
  • Breaking changes
  • Migration guides

​
Examples

# Get latest release notes
release_notes()

​
Use Cases

  • Check what’s new in latest version
  • Review breaking changes
  • Find migration instructions
  • Stay updated on product improvements
This is a discovery tool - no parameters required. Content is loaded from static resource file.

Build docs developers (and LLMs) love

Get started for freeTalk to us