Thegram Quickstart: Choose Local or Cloud, Then Read Safely

@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 observed | Connection / permission | Storage |
|---|---|---|---|
| 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. |

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.

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