@gram 2
doc d_5778a001327643799617b998ea2e6e00
t Thegram Quickstart: Choose Local or Cloud, Then Read Safely
d Choose local Mac or Cloud, meet current source prerequisites, then verify read-only access.
tag guides
tag quickstart
view document
::rich
# Thegram quickstart

Choose one connection: the local Mac MCP server for coding agents on the same Mac, or Thegram Cloud for ChatGPT/dots and OAuth-capable MCP clients. Local-only folders are not exposed to Cloud.

## Choose the connection

| Route | Prerequisites | First setup |
|---|---|---|
| Local coding agent | Apple silicon (arm64); macOS 26 or later; Node.js 22+; app open | The person enables Agent Access. Follow the canonical local install guide at https://thegram.one/install/agents.md. |
| Thegram Cloud | Thegram account; ChatGPT or OAuth-capable MCP client | Use https://vault.thegram.one/mcp with Streamable HTTP and OAuth; the Cloud guide embeds the current canonical ChatGPT account/plugin steps. |

## Local and Cloud: features, permissions and storage

| Route | Features | Connection / permission | Storage |
|---|---|---|---|
| Local Mac (owner-source supported) | MCP; Document, Dashboard, Graph UI; gram_recall modes: exact, keyword, semantic, hybrid, auto; embeddinggemma-2 semantic retrieval is conditional on model/index readiness. Dynamic; check gram_capabilities semantic status and index counts before semantic retrieval. | Thegram for Mac running; Agent Access (read or write) granted by the person | Local Mac folders plus connected Google Drive and Thegram Cloud vault mounts listed by gram_projects; each mount reports its read/write access. |
| Cloud (user-reported 2026-10-13) | MCP (15 tools); Document, Dashboard; search: exact, keyword; semantic search: unavailable | Thegram account; OAuth sign-in; running Mac required: no | Thegram Cloud vaults or Google Drive separately connected at vault.thegram.one |

Thegram for Mac 0.9.8 (build 33) was reported in use on 2026-10-13; this dated app observation is distinct from the current Mac release, which is sourced from thegram-desktop-release/evidence/release-0100/verification.json. Cloud runtime facts are dated user-reported observations, not an independently captured runtime test. Provenance: User review supplied 2026-10-13; reported runtime observations, not an independently captured test.

## First check: read-only

Start with the project or mount root, not a document path: gram_projects lists project names and mount keys. Call gram_brief with the exact returned project folder or mount key; its docs list supplies exact document paths. Choose an existing document from that list, then read it.

```js
gram_capabilities({})
gram_projects({})
gram_brief({ "folder": "<project folder or mount key returned by gram_projects>" })
gram_read({ "path": "<exact document path in gram_brief docs>" })
gram_read({ "path": "<same document path>", "section": "<heading returned by gram_read outline>" })
```

gram_read without optional arguments returns the outline. Use only a heading in that returned outline for the section read. Local-only folders are not visible from Cloud.

## Expected result

The intended authorized project or mount appears, gram_brief lists documents under it, and the chosen existing document returns its current revision/hash and outline. The section read returns that section. These checks do not change account state or content.

## Client distinctions

- Claude Code, Codex, OpenCode and OMP use the local Mac server; exact commands and host prompts come from the canonical local install guide at https://thegram.one/install/agents.md.
- ChatGPT chats and dots use Thegram Cloud. ChatGPT account/plugin steps are embedded from its canonical owner guide in the Cloud setup page.
- A generic MCP client must support Streamable HTTP and OAuth; use that client’s own sign-in UI rather than assuming ChatGPT controls.

## Optional first save and search

Keep installation and the checks above read-only. Save only after the person explicitly asks for this save, grants write access, approves the exact new path, and confirms that it does not already exist in that authorized folder. Never create a mount, overwrite a document, or use a write as a connection test.

Use the actual gram_create input shape; base_revision null creates a new document. Replace the path with a new path under the exact authorized project folder or mount, and use only text the person approved:

```js
gram_create({
  "path": "<authorized-folder>/setup-notes.gram",
  "title": "Setup notes",
  "base_revision": null,
  "content": "# Setup notes"
})
```

Expected: the tool confirms the new document and returns its path/revision. Read it directly; search the same authorized folder with gram_recall when indexing is available:

```js
gram_read({ "path": "<exact path returned by gram_create>" })
gram_recall({
  "query": "setup notes",
  "folder": "<same authorized folder or mount key>",
  "top_k": 5
})
```

Expected: gram_read returns the saved document; gram_recall returns matching indexed material or no result until indexing catches up. Both retrieval calls are read-only.

Sources: https://thegram.one/install/agents.md · https://thegram.one/install/chatgpt.md · https://thegram.one/agent-memory/
::end

@gram-history 6
@rev 0 2026-10-12T13:01:57.739Z agent agent=omp-coding-agent 468b37a815c0da0864bda1f47d80aff4fb17f50f19c71538b3e085aff50af576
@rev 1 2026-10-12T13:38:02.457Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-8cbfe8bfee27b1474d3966f5 dig=4538821e385d8c8a kind=SourceImported a03cf8cf61e90b9f2e1e0a30ec6bd562abf3defb65d17da9be1f2c8afdc7b10c
@@ 3 5 1
::rich
@@ 10 1 1
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.
@@ 14 4 4
| 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). |
@@ 21 1 1
Start with inspection. Do not call gram_create or gram_patch during setup or this first check.
@@ 23 4 4
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.
@@ 28 1 1
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.
@@ 30 1 1
## What success looks like
@@ 32 1 1
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.
@@ 36 3 7
- 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.
@rev 2 2026-10-12T13:47:34.113Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-f30b9bd1a403fa9013cad7dc dig=9ece69ae0cc8d381 kind=SourceImported 448d5cfb48f249801f0c08fdc320cc6b998fdaf78ee775464e7cd6ea3df882bc
@@ 7 1 1
::body
@rev 3 2026-10-12T14:10:29.110Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-a1859cb5ce4e27a100baebee dig=6fdc6a21fe40e437 kind=SourceImported 2b5b35bed9bd69bab63732083bb4abd70fe2133dd0d378e1ce6584a617fecb47
@@ 16 2 2
| Local coding agent | Apple silicon (arm64); macOS 26 or later; Node.js 22+; app open | The person enables Agent Access. Follow the [canonical local install guide](https://thegram.one/install/agents.md). |
| Thegram Cloud | Thegram account; ChatGPT or OAuth-capable MCP client | Use https://vault.thegram.one/mcp with Streamable HTTP and OAuth. ChatGPT follows its [canonical guide](https://thegram.one/install/chatgpt.md). |
@@ 21 1 1
Do not call gram_create or gram_patch during setup or this first check.
@@ 23 7 4
1. Call gram_capabilities. Expect available tools and server capacity; this does not prove a particular document is accessible.
2. Call gram_projects. Use only a returned project path or mount key; local Mac-only folders are not visible from Cloud.
3. Call gram_brief for an exact existing path returned by gram_projects. Expect title, current revision/hash, counts and recent changes.
4. Call gram_read for that path without section to receive its outline, then call gram_read again with a heading from that outline as section.
@@ 31 1 1
Sequence: gram_capabilities → gram_projects → gram_brief(path=<returned path>) → gram_read(path=<same path>) → gram_read(path=<same path>, section=<returned heading>). These calls are read-only.
@@ 35 1 1
The selected identity can see an authorized project or vault and an existing document with revision context; the focused read returns the requested section. Installation alone does not prove app availability, OAuth authorization or document scope. Stop on errors; do not change mounts or try writes as a connectivity check.
@@ 39 31 3
- Claude Code, Codex, OpenCode and OMP use the local Mac server; their commands and host prompts live only in the [canonical local install guide](https://thegram.one/install/agents.md).
- ChatGPT chats and dots use the Cloud endpoint and ChatGPT plugin/custom MCP UI. The ChatGPT Mac app install sequence is reported verified in the public install source.
- A generic MCP client must support Streamable HTTP and OAuth. Published source documents endpoint, Streamable HTTP and OAuth; no provider-specific generic-client behavior is asserted.
@rev 4 2026-10-13T01:39:04.962Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-66f78546050855e8c60f1da1 dig=70ad4438dfddad5c kind=SourceImported d9e89fae9d29cc2115dffddcec35203a78f22d699956263037f95947a417aac3
@@ 19 9 0
@rev 5 2026-10-13T01:47:53.431Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-ebe6daf87df4d2b5685e7ab1 dig=d691af739df52af4 kind=SourceImported 46f5aab60e612c84b3f9f36925a369679be065886690baee190f58b30cefe1dd
@@ 26 1 1
Runtime observations dated 2026-10-13: User review supplied 2026-10-13; reported product observations, not an independently captured test.
@rev 6 2026-10-13T02:11:27.613Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-64ca40a03228fc6b5fdec0f4 dig=aeeda897b6a8f060 kind=SourceImported 8870f4228257ffebc7a7fbcfc3e3304e6f3b672b80a96052308c27620fdf0b33
@@ 21 1 1
| Route | Features observed | Connection / permission | Storage |
@@ 23 2 2
| Local Mac | MCP; Graph UI | Thegram for Mac running; Agent Access enabled by the person | Folders stored on the Mac; local-only folders are not exposed to Cloud. |
| Cloud | MCP (15 tools); Document, Dashboard; search: exact, keyword; semantic search: unavailable | Thegram account; OAuth sign-in; running Mac required: no | Thegram Cloud vault; Google Drive only when separately connected and authorized. |
@@ 26 1 1
Runtime observations dated 2026-10-13: User review supplied 2026-10-13; reported product observations, not an independently captured test. The Mac version/build are date-bounded observations, not a current-release pointer. Keep current public Mac release values derived from owner release evidence. If a later owner release differs, refresh this observation only with a new runtime review; never silently relabel the old observation.
@rev 7 2026-10-14T02:42:46.784Z portal-product-quickstarts agent=developer-doc-generator req=portal-product-quickstart-cbf0a5d0576e945a809d62e8 dig=51524c75ca30131a kind=SourceImported 69d82affb91361cb0d9f3ee86d666f3fc95193893c6c6037681e5dd404026248
@@ 26 1 1
Thegram for Mac 0.9.8 (build 33) was reported in use on 2026-10-13; this dated app observation is distinct from the current Mac release, which is sourced from thegram-desktop/evidence/release-098/verification.json. Cloud runtime facts are dated user-reported observations, not an independently captured runtime test. Provenance: User review supplied 2026-10-13; reported runtime observations, not an independently captured test.