Getting Started
Thegram Quickstart: Choose Local or Cloud, Then Read Safely
Explore as .gram
Thegram quickstart
Thegram keeps project memory in .gram documents with revision history. Choose one connection: the local Mac MCP server for a coding agent on the same Mac, or Thegram Cloud for ChatGPT/dots and OAuth-capable MCP clients. These are different routes and do not share automatic access to the same local-only folders.
Choose the connection
Route | Prerequisites | Where the memory lives | First setup |
Local coding agent | Apple silicon (arm64); macOS 26 or later; Node.js 22 or later; Thegram for Mac open | Local Mac folders; agent connection works only while the app is open | The person enables Agent Access in Thegram → Settings → Agent Connections. Use the host-specific flow in the canonical local install guide. |
Thegram Cloud | Thegram account; ChatGPT or an OAuth-capable MCP client | Thegram Cloud vault; Google Drive only when separately connected/authorized | Add the MCP server at https://vault.thegram.one/mcp with OAuth. ChatGPT has a separate UI flow in its canonical install guide. |
First check: read-only
Start with inspection. Do not call gram_create or gram_patch during setup or this first check.
Call gram_capabilities. Expect the available read and write tools and server capacity; this is capability information, not proof that a particular document is accessible.
Call gram_projects. Expect only the projects and mounts available to the current connection. Use the exact returned project path or mount key; local Mac-only folders are not visible from cloud.
Call gram_brief for a path returned by gram_projects (or an existing document path supplied by the person). Expect the document title, current revision/hash, counts and recent changes in a compact summary.
Call gram_read on that same existing path with outline=true to see its headings. Then call gram_read again with a section name from the returned outline to read only that section. Expect the document path, revision/hash, requested section and Markdown.
Example sequence (tool calls, not shell commands): gram_capabilities → gram_projects → gram_brief(path=<returned path>) → gram_read(path=<same path>, outline=true) → gram_read(path=<same path>, section=<returned heading>). All calls above are read-only.
What success looks like
You see the authorized project or vault, a real existing document and its current revision, and a short requested section. A successful plugin installation alone does not prove the app is running, OAuth is authorized, or that a selected document is in scope. Stop if a tool returns an error; follow the route-specific troubleshooting instead of changing mounts or retrying writes.
Client distinctions
Claude Code, Codex, OpenCode and OMP on the same Mac use Thegram for Mac's local MCP server. Their plugin commands, doctor check, user prompts and platform-specific differences are in the canonical local install guide; that file is the only maintained command source.
ChatGPT chats and dots use the ChatGPT plugin/custom MCP UI, OAuth and the cloud endpoint. The published ChatGPT guide documents a ChatGPT Mac app install check; it does not claim a separate dot installation test.
A generic MCP client uses the cloud Streamable HTTP endpoint with OAuth only if that client supports the documented sign-in flow. The ChatGPT UI sequence is not a generic-client command, and no provider-specific generic-client behavior is implied.
Sources and prerequisites
The local guide states arm64, macOS 26 or later, Node.js 22 or later, and the app's Agent Connections setup. The ChatGPT guide states the cloud URL/OAuth flow. See local setup and cloud setup for each route.
Sources: https://thegram.one/install/agents.md · https://thegram.one/install/chatgpt.md · https://thegram.one/agent-memory/
sha256:9be32a96c435f0ebfdc8110b2abc327f6412e8373b042623f662a73539a460c6@gram 2
doc d_5778a001327643799617b998ea2e6e00
t Thegram Quickstart: Choose Local or Cloud, Then Read Safely
::rich
# Thegram quickstart
Thegram keeps project memory in .gram documents with revision history. Choose one connection: the local Mac MCP server for a coding agent on the same Mac, or Thegram Cloud for ChatGPT/dots and OAuth-capable MCP clients. These are different routes and do not share automatic access to the same local-only folders.
## Choose the connection
| Route | Prerequisites | Where the memory lives | First setup |
|---|---|---|---|
| Local coding agent | Apple silicon (arm64); macOS 26 or later; Node.js 22 or later; Thegram for Mac open | Local Mac folders; agent connection works only while the app is open | The person enables Agent Access in Thegram → Settings → Agent Connections. Use the host-specific flow in [the canonical local install guide](https://thegram.one/install/agents.md). |
| Thegram Cloud | Thegram account; ChatGPT or an OAuth-capable MCP client | Thegram Cloud vault; Google Drive only when separately connected/authorized | Add the MCP server at https://vault.thegram.one/mcp with OAuth. ChatGPT has a separate UI flow in [its canonical install guide](https://thegram.one/install/chatgpt.md). |
## First check: read-only
Start with inspection. Do not call gram_create or gram_patch during setup or this first check.
1. Call gram_capabilities. Expect the available read and write tools and server capacity; this is capability information, not proof that a particular document is accessible.
2. Call gram_projects. Expect only the projects and mounts available to the current connection. Use the exact returned project path or mount key; local Mac-only folders are not visible from cloud.
3. Call gram_brief for a path returned by gram_projects (or an existing document path supplied by the person). Expect the document title, current revision/hash, counts and recent changes in a compact summary.
4. Call gram_read on that same existing path with outline=true to see its headings. Then call gram_read again with a section name from the returned outline to read only that section. Expect the document path, revision/hash, requested section and Markdown.
Example sequence (tool calls, not shell commands): gram_capabilities → gram_projects → gram_brief(path=<returned path>) → gram_read(path=<same path>, outline=true) → gram_read(path=<same path>, section=<returned heading>). All calls above are read-only.
## What success looks like
You see the authorized project or vault, a real existing document and its current revision, and a short requested section. A successful plugin installation alone does not prove the app is running, OAuth is authorized, or that a selected document is in scope. Stop if a tool returns an error; follow the route-specific troubleshooting instead of changing mounts or retrying writes.
## Client distinctions
- Claude Code, Codex, OpenCode and OMP on the same Mac use Thegram for Mac's local MCP server. Their plugin commands, doctor check, user prompts and platform-specific differences are in the canonical local install guide; that file is the only maintained command source.
- ChatGPT chats and dots use the ChatGPT plugin/custom MCP UI, OAuth and the cloud endpoint. The published ChatGPT guide documents a ChatGPT Mac app install check; it does not claim a separate dot installation test.
- A generic MCP client uses the cloud Streamable HTTP endpoint with OAuth only if that client supports the documented sign-in flow. The ChatGPT UI sequence is not a generic-client command, and no provider-specific generic-client behavior is implied.
## Sources and prerequisites
The local guide states arm64, macOS 26 or later, Node.js 22 or later, and the app's Agent Connections setup. The ChatGPT guide states the cloud URL/OAuth flow. See [local setup](https://docs.thegram.one/guides/local-setup/) and [cloud setup](https://docs.thegram.one/guides/cloud-setup/) for each route.
Sources: https://thegram.one/install/agents.md · https://thegram.one/install/chatgpt.md · https://thegram.one/agent-memory/
::end