Guides
Connect an AI Client to Thegram Cloud Safely
A practical guide to OAuth, mount discovery, cloud vaults, Drive, safe retrieval and revision-aware updates.
The cloud integration lets a supported AI client use Thegram memory through a remote MCP service. It is useful when people need shared project context without keeping a Mac app connected to every request. That connection does not mean an assistant can copy everything it reads: tool connection, data-source access and permission to save a particular fact are separate decisions. The steps below focus on making those boundaries visible.
Connect and discover
Install the cloud plugin or configure a compatible MCP client for the documented Streamable HTTP service and OAuth flow. Use Thegram’s public install guide for the host in use, sign in through the provider’s normal flow and complete any required authorization or reauthorization prompts. A plugin ZIP, a configured MCP connection and an entry in a host directory are different things; a package being available does not prove end-user installation or host approval.
After connecting, call gram_projects to discover mounts. Use the exact key returned by the service, not its display name or a guessed identifier. A cloud-vault document uses a top-level path such as @mounts/<vault-id>/project.gram. Cloud vault writes are limited to top-level .gram documents; Google Drive mounts can expose folders. Respect the reported access level and the requested destination. A denied write is not a reason to copy the content to another mount.
First discovery can create a default writable vault for an account with none. That is account setup, not consent to create records or import content. A viewer cannot write. If an operation requires provider consent or authentication, ask the person to complete the normal authorization flow rather than attempting a workaround.
Retrieve context before answering
Start with gram_brief for the relevant document or folder. It reports current revisions and hashes, open work and an incremental changes cursor. Use gram_recall to find relevant records, then gram_context with only the fields needed to answer. Use gram_read for an outline or section and gram_relations when explicit links matter. Similar wording does not create a graph edge; only stored links do. Follow pagination and say when coverage is incomplete.
For later visits, pass the next cursor from gram_brief to gram_changes using since: next. The public plugin contract defines this as an exclusive recorded-time continuation, not a request for historical state. For a past state, request an explicit revision, recorded time or effective time. Distinguish when a fact applied from when it was recorded.
Make careful, recoverable changes
Before editing an existing document, take base_revision and expected_hash from the latest brief or a successful write response. Submit one intentional gram_patch with a stable request_id and typed operations. Give real tasks and risks appropriate statuses, place durable prose in its section and use source records for actual provenance. A record that is not placed may exist without appearing in the readable document. Do not invent owners, dates or evidence.
If a write reports STALE_REVISION or STORAGE_CONFLICT, read the current version, inspect affected prose and records, preserve other writers’ changes and construct a new intentional patch. Do not replay a stale patch unchanged. If a response is lost, inspect the destination before retrying; gram_create has no request ID, so check whether the document exists before another create. For Drive, claim remote persistence only when the response reports sync.state as synced. A successful tool call alone does not prove synchronization.
Example: preserve a launch decision
A product lead asks, “What did we decide about the staged launch, and what remains?” Discover the exact writable mount, brief the project document, recall rollout decisions and read relevant decision and task records with context. Answer first without writing. If asked to record an accepted exception, check the evidence, add one decision linked to its project and supporting evidence, place it in Decisions, and add a separate open task only if someone agreed that work remains. Read back the records and body; mention the revision and sync state only after checking the receipt.
Limits and further reading
The public plugin docs at revision 1f92e8a state that cloud semantic search is unavailable and recall mode auto falls back to keyword matching. This describes the cloud integration, not a live capability check; query gram_capabilities for the active service and do not assume local parity. The package implements MCP integration, not Slack or Gmail retrieval itself, although its shipped example prompt can ask an assistant to summarize connected sources. Server onboarding may describe broader automatic capture. Requiring the user’s explicit request before saving and reviewing the result are human operating guidance, not product-enforced consent controls.
Use the official installation guide for the host, public cloud package README and committed contract for versioned behavior, and check runtime capabilities before relying on search or a tool. The internal Vault implementation was inspected separately; it is not publicly available. The local-agent guide covers project-folder hooks and app permissions; installing cloud integration does not include those.
Public package overview, inspected at commit 1f92e8a.
https://github.com/clab-one/thegram-plugin/blob/1f92e8a/README.mdPublic contract source at commit 1f92e8a, including the cloud semantic-search limitation and the gram_changes cursor behavior.
https://github.com/clab-one/thegram-plugin/blob/1f92e8a/skills/thegram-cloud/references/contracts.mdPublic installation instructions; the client’s current authorization flow should be followed.
https://thegram.one/install/Internal Vault source reviewed at revision a193a19; not publicly available.
Use exact mount keys and never redirect a failed write to another destination.
After authorized cloud or Drive changes, inspect the relevant records and check reported synchronization state.
Public cloud docs state semantic search is unavailable and auto falls back to keyword matching; verify live capabilities.
Connect an AI Client to Thegram Cloud Safely
r0 · Time unknown · Unknown author
A practical guide to OAuth, mount discovery, cloud vaults, Drive, safe retrieval and revision-aware updates.
Source4
Knowledge3
sha256:a70e6f19e6993a1c99164cca0ca32214f3eb610049e82f484e135b42cdf25227@gram 2
doc blog-cloud-agent-guide
t Connect an AI Client to Thegram Cloud Safely
d A practical guide to OAuth, mount discovery, cloud vaults, Drive, safe retrieval and revision-aware updates.
tag guides
view document
::rich
# Connect an AI Client to Thegram Cloud Safely
The cloud integration lets a supported AI client use Thegram memory through a remote MCP service. It is useful when people need shared project context without keeping a Mac app connected to every request. That connection does not mean an assistant can copy everything it reads: tool connection, data-source access and permission to save a particular fact are separate decisions. The steps below focus on making those boundaries visible.
## Connect and discover
Install the cloud plugin or configure a compatible MCP client for the documented Streamable HTTP service and OAuth flow. Use Thegram’s public install guide for the host in use, sign in through the provider’s normal flow and complete any required authorization or reauthorization prompts. A plugin ZIP, a configured MCP connection and an entry in a host directory are different things; a package being available does not prove end-user installation or host approval.
After connecting, call gram_projects to discover mounts. Use the exact key returned by the service, not its display name or a guessed identifier. A cloud-vault document uses a top-level path such as @mounts/<vault-id>/project.gram. Cloud vault writes are limited to top-level .gram documents; Google Drive mounts can expose folders. Respect the reported access level and the requested destination. A denied write is not a reason to copy the content to another mount.
First discovery can create a default writable vault for an account with none. That is account setup, not consent to create records or import content. A viewer cannot write. If an operation requires provider consent or authentication, ask the person to complete the normal authorization flow rather than attempting a workaround.
## Retrieve context before answering
Start with gram_brief for the relevant document or folder. It reports current revisions and hashes, open work and an incremental changes cursor. Use gram_recall to find relevant records, then gram_context with only the fields needed to answer. Use gram_read for an outline or section and gram_relations when explicit links matter. Similar wording does not create a graph edge; only stored links do. Follow pagination and say when coverage is incomplete.
For later visits, pass the next cursor from gram_brief to gram_changes using since: next. The public plugin contract defines this as an exclusive recorded-time continuation, not a request for historical state. For a past state, request an explicit revision, recorded time or effective time. Distinguish when a fact applied from when it was recorded.
## Make careful, recoverable changes
Before editing an existing document, take base_revision and expected_hash from the latest brief or a successful write response. Submit one intentional gram_patch with a stable request_id and typed operations. Give real tasks and risks appropriate statuses, place durable prose in its section and use source records for actual provenance. A record that is not placed may exist without appearing in the readable document. Do not invent owners, dates or evidence.
If a write reports STALE_REVISION or STORAGE_CONFLICT, read the current version, inspect affected prose and records, preserve other writers’ changes and construct a new intentional patch. Do not replay a stale patch unchanged. If a response is lost, inspect the destination before retrying; gram_create has no request ID, so check whether the document exists before another create. For Drive, claim remote persistence only when the response reports sync.state as synced. A successful tool call alone does not prove synchronization.
## Example: preserve a launch decision
A product lead asks, “What did we decide about the staged launch, and what remains?” Discover the exact writable mount, brief the project document, recall rollout decisions and read relevant decision and task records with context. Answer first without writing. If asked to record an accepted exception, check the evidence, add one decision linked to its project and supporting evidence, place it in Decisions, and add a separate open task only if someone agreed that work remains. Read back the records and body; mention the revision and sync state only after checking the receipt.
## Limits and further reading
The public plugin docs at revision 1f92e8a state that cloud semantic search is unavailable and recall mode auto falls back to keyword matching. This describes the cloud integration, not a live capability check; query gram_capabilities for the active service and do not assume local parity. The package implements MCP integration, not Slack or Gmail retrieval itself, although its shipped example prompt can ask an assistant to summarize connected sources. Server onboarding may describe broader automatic capture. Requiring the user’s explicit request before saving and reviewing the result are human operating guidance, not product-enforced consent controls.
Use the official installation guide for the host, public cloud package README and committed contract for versioned behavior, and check runtime capabilities before relying on search or a tool. The internal Vault implementation was inspected separately; it is not publicly available. The local-agent guide covers project-folder hooks and app permissions; installing cloud integration does not include those.
[[src-cloud-readme]]
[[src-cloud-contract]]
[[src-install-cloud]]
[[src-vault-contract]]
[[knowledge-cloud-destination]]
[[knowledge-cloud-recovery]]
[[knowledge-cloud-search]]
::end
SRC src-cloud-readme
t thegram-cloud README
d Public package overview, inspected at commit 1f92e8a.
ref https://github.com/clab-one/thegram-plugin/blob/1f92e8a/README.md
SRC src-cloud-contract
t Committed cloud MCP contract
d Public contract source at commit 1f92e8a, including the cloud semantic-search limitation and the gram_changes cursor behavior.
ref https://github.com/clab-one/thegram-plugin/blob/1f92e8a/skills/thegram-cloud/references/contracts.md
SRC src-install-cloud
t Official client installation guide
d Public installation instructions; the client’s current authorization flow should be followed.
ref https://thegram.one/install/
SRC src-vault-contract
t Vault service implementation contract
d Internal Vault source reviewed at revision a193a19; not publicly available.
K knowledge-cloud-destination
t Preserve the requested mount
d Use exact mount keys and never redirect a failed write to another destination.
source src-cloud-contract
K knowledge-cloud-recovery
t Read back and reconcile writes
d After authorized cloud or Drive changes, inspect the relevant records and check reported synchronization state.
source src-cloud-contract
K knowledge-cloud-search
t Check current cloud search behavior
d Public cloud docs state semantic search is unavailable and auto falls back to keyword matching; verify live capabilities.
source src-cloud-contractSource and build provenance
Renderer API: thegram-web-render/1. Core source: git+https://github.com/clab-one/thegram-format.git?rev=625edecee877ddf5f6c303cb478c64fa4cbca651#625edecee877ddf5f6c303cb478c64fa4cbca651.
The download file hash covers exact .gram bytes; the renderer Source sheet reports the source used for its selected revision.
This page was generated from the canonical cloud-agent-guide.gram source.
- Download file SHA-256
a70e6f19e6993a1c99164cca0ca32214f3eb610049e82f484e135b42cdf25227- Renderer
- Existing local Thegram renderer (local Thegram renderer); rendered at build time.
- Renderer document
blog-cloud-agent-guide- Selected revision
- r0
Revision navigation and historical search are not offered on this static publication. The displayed revision is the one rendered from this exact source during the build.