# Agentage Memory - Docs

Connect any MCP client to one shared markdown memory through a single endpoint. Sign in with OAuth and Claude, ChatGPT, Cursor, and your other AI tools read and write the same notes - plain markdown you own and can export anytime.

## Connect

- MCP endpoint: `https://memory.agentage.io/mcp` (Streamable HTTP)
- Auth: OAuth 2.1 with PKCE and dynamic client registration - sign in once in the browser, no API key.

### Claude Code

1. Run `claude mcp add --transport http agentage-memory https://memory.agentage.io/mcp`
2. Run `/mcp` and complete the OAuth sign-in.
3. A connector you add in Claude.ai also syncs here automatically.

### Claude (claude.ai & Desktop)

1. One-click: [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Agentage%20Memory&connectorUrl=https%3A%2F%2Fmemory.agentage.io%2Fmcp) - opens with the server prefilled; review, confirm, and sign in.
2. Or manually: Settings > Connectors > Add custom connector, paste `https://memory.agentage.io/mcp`.

### VS Code

1. One-click: [Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22agentage-memory%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmemory.agentage.io%2Fmcp%22%7D).
2. Or add the server to `.vscode/mcp.json` (or run the `MCP: Add Server` command):
3. ```json
   {
     "servers": {
       "agentage-memory": {
         "type": "http",
         "url": "https://memory.agentage.io/mcp"
       }
     }
   }
   ```
4. VS Code opens the browser for the OAuth sign-in on first use.

### Cursor

1. One-click: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=agentage-memory&config=eyJ1cmwiOiJodHRwczovL21lbW9yeS5hZ2VudGFnZS5pby9tY3AifQ==), then sign in when prompted.
2. Or add the server to `~/.cursor/mcp.json`:
3. ```json
   {
     "mcpServers": {
       "agentage-memory": {
         "url": "https://memory.agentage.io/mcp"
       }
     }
   }
   ```

### ChatGPT

1. Open [Settings > Apps & Connectors](https://chatgpt.com/#settings/Connectors) > Advanced settings > enable Developer Mode > Create (paid plans, not Free; ChatGPT has no one-click link, so add it by hand).
2. Paste `https://memory.agentage.io/mcp` and sign in when prompted.

## MCP tools

Once connected, every client gets six memory operations:

- `memory__search`: Find notes by keyword across the whole memory.
- `memory__read`: Read a note by path.
- `memory__write`: Create or replace a note.
- `memory__edit`: Apply a targeted edit to a note.
- `memory__list`: Browse the folder tree - subfolders with file counts, two levels deep.
- `memory__delete`: Remove a note.

## Example prompts

- "Search my memory for "postgres" and read the top result."
  - Outcome: Ranks notes mentioning postgres by match count, then returns the top note in full (frontmatter + markdown body). (`memory__search -> memory__read`)
- "Save a note at projects/acme/stack.md: we use Postgres for full-text search."
  - Outcome: Creates (or fully replaces) that note. It persists server-side and is readable from every AI you connect to the same account. (`memory__write`)
- "List everything under projects/ and tag the roadmap note as launched."
  - Outcome: Shows the folder tree under projects/ (subfolders with file counts + notes), then shallow-merges a launched tag into the roadmap note frontmatter without rewriting the body. (`memory__list -> memory__edit`)

The memory tools run only when your request is about your notes - everyday questions like facts, math, or writing are answered normally, without touching your memory.

## REST API

A read-only HTTP surface at `https://api.agentage.io`. Auth: OAuth 2.1 bearer token - the same token issued when you connect any MCP client. No API key. Rate limited to 60 requests per minute per IP.

- `GET /v1/vaults`: List the vaults your token can see.
- `GET /v1/vaults/{vault}`: Vault stats: counts, size, last activity.
- `GET /v1/vaults/{vault}/notes`: List notes, paginated, optionally by folder.
- `GET /v1/vaults/{vault}/notes/{path}`: Read one note: frontmatter + markdown body.
- `GET /v1/vaults/{vault}/search`: Keyword search, ranked, snippets only.
- `GET /v1/vaults/{vault}/export`: Stream the vault as a cloneable git bundle.

Full reference: https://agentage.io/docs/rest-api

## Limitations

- Notes are plain markdown addressed by path (e.g. work/tasks/foo.md), not by title or ID.
- Search is literal keyword/substring matching - not semantic or vector search; search one distinctive keyword, not a phrase.
- search returns ranked paths + snippets, never full bodies - use read for the whole note.
- list shows the folder tree two levels deep, up to 100 entries per folder - call it again with a subfolder to browse deeper.
- edit shallow-merges top-level frontmatter keys and cannot remove a key; use write to fully replace a note.
- delete is a recoverable soft-delete (kept in history), not a hard wipe.
- One memory per account; connect the same account in each client to share it. Data is stored in the EU and exportable anytime.

HTML version: https://agentage.io/docs