---
title: "Memory URLs"
description: "Address notes directly with memory:// paths, including project-prefixed routing."
canonical_url: "https://docs.basicmemory.com/concepts/memory-urls"
---
# Memory URLs

> Address notes directly with memory:// paths, including project-prefixed routing.

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 or permalink

```text
memory://auth-approaches-2024
memory://Auth Approaches 2024
```

Both a permalink and an exact note title resolve. Exact matches — file path, permalink, and title — are always tried first, including on project-prefixed URLs like `memory://main/Auth Approaches 2024`. `bm_context` doesn't fall back to fuzzy matching: a URL that names no note returns nothing, and a title shared by more than one note is refused, so pass the permalink instead.

### By path

```text
memory://docs/authentication
memory://docs/authentication.md
```

### By wildcard

```text
memory://docs/*
memory://auth*
```

---

## Project-prefixed URLs

Memory URLs can include project scope as the first path segment:

```text
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 — you can write it in a relation:

```markdown
- relates_to [[research::specs/api]]
```

The `project::note-path` form is treated as `project/note-path`, and the same syntax works inside `memory://` URLs. 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 `bm_read` and `bm_context` accept memory URLs as their primary input, and assistant workflows pass them between calls to maintain stable references.

---

## Notes as MCP resources

As of [v0.24](https://docs.basicmemory.com/whats-new/v0-24), every `memory://` URL Basic Memory hands out is also a readable MCP resource. A client that supports `resources/read` can fetch `memory://<project>/<path>` and get the note's raw Markdown, frontmatter included. The identifier can be a permalink, title, or file path. An unknown note points you at `bm_search`, and a binary file points at `bm_read`.

Two other resource families share the scheme:

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      Returns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        memory://man
      </code>
    </td>
    
    <td>
      Index of Basic Memory's built-in manual
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memory://man/<page>
      </code>
    </td>
    
    <td>
      One manual page, such as <code>
        memory://man/bm-search(3)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        memory://<workspace>/<project>/info
      </code>
    </td>
    
    <td>
      Project information as JSON
    </td>
  </tr>
</tbody>
</table>

Each MCP tool has a section-3 manual page with its parameters, verified examples, and gotchas, and clients that browse `resources/list` see every page with its summary. From the terminal, `bm man <topic>` prints the same pages. See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference).

---

## Resolution behavior

For 1.0 note and search tools, URLs can carry a recognized project prefix. Without that prefix, pass `project` when several projects are addressable; a configured default does not supply implicit scope. A single addressable project can be selected implicitly. The full resolution order — including local-server project constraints — is covered in the [local User Guide](https://docs.basicmemory.com/local/user-guide#memory-url-resolution-local-server); these controls aren't exposed in cloud.

---

## 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

---

## Next steps

<card-group>
<card icon="i-lucide-wrench" title="MCP Tools Reference" to="https://docs.basicmemory.com/reference/mcp-tools-reference">

See which tools accept memory URLs.

</card>

<card icon="i-lucide-bot" title="AI Assistant Guide" to="https://docs.basicmemory.com/reference/ai-assistant-guide">

Teach your assistant when and how to use Basic Memory.

</card>
</card-group>


## Sitemap

See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.