Thegram Quickstart: Choose Local or Cloud, Then Read Safely · r9
Archived revision r9, recorded 2026-10-14T08:01:14.301Z by portal-product-quickstarts. Current page: Thegram Quickstart: Connect Cloud Memory, Then Read Safely.
Thegram quickstart
Section titled “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
Section titled “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
Section titled “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 |
One type, one dashboard
Section titled “One type, one dashboard”Core 2.0.1 resolves one dashboard per declared document type. The client renders its single ResolvedView/1 result; it does not choose another ViewSpec or compute its own recommendation.
| Document type | Dashboard |
|---|---|
| schedule@1 | Journal |
| project@1 | Project Tracker |
| knowledge@1 | Knowledge |
Without a template declaration, Core recommends a dashboard and the dashboard is read-only. If no recommendation is eligible, it falls back to Project Tracker, still read-only. An unknown id/version or malformed declaration has no dashboard: show the document and Core diagnostics without automatically choosing another type.
A folder opens one home screen. There are no per-document screen tabs, sidebar screen lists, ViewSpec switchers or search/filter/sort/group query toolbar. Document and dashboard are representations of the same file, not separate copies.
Templates still choose a type when creating a document, validate governed writes, supply AI authoring rules and define typed actions. A read-only recommended dashboard does not forbid ordinary document editing through the normal authorized write path.
For declaration and writing rules, see View templates.
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-200/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
Section titled “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.
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
Section titled “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
Section titled “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
Section titled “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:
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:
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/
Source and renderer evidence
- Canonical source SHA-256
5ed2a602b802ea2e281917618a193d5d49d132a2d1dc391abc68d58857281144- Selected revision
r9 · sha256:0a711b5ce1d79604beaf04d4bcc20322b67a09de2628eeadbd7c00674f43888a- Local renderer
configured local Thegram renderer · API thegram-web-render/1- Core source
git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557
Canonical source: 9.gram