Memory URLs
Basic Memory is a knowledge base that you and your AI share. Memory URLs are how notes are addressed — by your AI, by CLI commands, and by links between notes.
Every note in Basic Memory has an address — a memory:// URL that works like a web link for your knowledge base. Your AI uses these behind the scenes to read notes, follow connections, and build context. You'll see them in tool output and can use them directly when you want to point your AI at something specific.
Basic forms
By title/permalink
memory://auth-approaches-2024
By path
memory://docs/authentication
memory://docs/authentication.md
By wildcard
memory://docs/*
memory://auth*
Project-prefixed URLs
With project-prefixed permalink behavior enabled (default), memory URLs can include project scope:
memory://main/docs/authentication
memory://research/specs/search-ranking
This is useful when the same note title exists in multiple projects.
Cross-project references in links
Within notes, project namespace syntax is normalized:
project::note-path
is treated as:
project/note-path
This improves cross-project resolution and keeps links explicit.
Where Memory URLs are used
Your AI uses memory URLs when reading notes, building context, and following links between notes. You can also use them directly in conversation — "read memory://docs/authentication" — or in CLI commands.
Behind the scenes, tools like read_note and build_context accept memory URLs as their primary input, and assistant workflows pass them between calls to maintain stable references.
Resolution behavior
At runtime, Basic Memory resolves memory URLs in this order:
1. Project constraints
If the MCP server was started with BASIC_MEMORY_MCP_PROJECT=research, all URLs are resolved within the research project regardless of any prefix in the URL:
memory://docs/auth → resolves in "research" project only
2. Explicit project prefix
If no constraint is set, the URL is checked for a project prefix. The first path segment is compared against known project names:
memory://main/docs/auth → resolves in "main" project
memory://research/specs/api → resolves in "research" project
3. Default project fallback
If no constraint exists and no project prefix matches, the URL resolves in the default project:
memory://docs/auth → resolves in default project (typically "main")
Project-prefix extraction
When permalinks_include_project is enabled (the default), Basic Memory checks whether the first path segment of a URL matches a known project name. If it does, that segment is stripped and used as the project context:
memory://main/specs/api-design
^^^^ → project = "main"
^^^^^^^^^^^^^^^^ → path = "specs/api-design"
If the first segment doesn't match any known project, the entire path is treated as a note path within the default project.
Best practices
- Use project-prefixed URLs in multi-project workflows
- Prefer permalinks for stability over titles when possible
- Use wildcards for discovery, then switch to exact references