Thegram Cloud and Local Agent Integrations: Two Different Architectures · r1

Archived revision r1, recorded 2026-10-12T13:09:34.996Z. Current page: Thegram Cloud and Local Agent Integrations: Two Different Architectures.

Thegram offers a cloud integration for supported AI clients and a local thegram-memory integration for coding agents. They share document concepts and tool names, but they are not two installation methods for the same service. Cloud access reaches a remote vault through OAuth; local access passes through the running Thegram Mac app and its Agent Connections permission. Separating those paths prevents assumptions about access, data location or supported behavior from leaking across boundaries.

Cloud path: client to remote vault

The cloud client uses Streamable HTTP with OAuth at the documented MCP service. It does not depend on a running Mac app. The Vault service authenticates the caller, resolves identity and checks membership in the requested vault for each read or write. Authentication does not confer membership. The public plugin can expose MCP tools after connection, but authorization to a particular vault resource is evaluated per operation.

The client calls gram_projects and must use the exact mount key returned, not a display name or guessed identifier. A cloud-vault document is top-level and uses a .gram filename constrained by service path rules; Drive mounts can include folders. A viewer can read but not write. First discovery may create a default writable vault when an account has none, but that setup does not authorize content capture or new records. Google sign-in for identity is also distinct from an explicit Drive connection.

Cloud-vault writes use conditional revision/hash data and a request identifier, and the service validates complete .gram documents with its pinned Gram Core binary before publishing a new head. A stale write requires re-reading and reconciling; it is not an invitation to change destinations. Drive synchronization is separate and should be reported complete only when the response says synced. Drive file-head revision checks are best effort, not atomic compare-and-swap.

Local path: agent to app proxy

The public thegram-memory package is a Node integration with hooks, adapters, repository-folder mapping and a local MCP proxy. The agent connects to the package, which routes MCP calls through the app’s local connection. The person must set Agent Access to the intended level in Thegram → Settings… → Agent Connections. Off disables access, Read permits inspection, and Read and Write is required for changes. The app must be running and Connection should report Running. This is an explicit app permission, not a preference inside the agent plugin.

By default, a repository maps to a vault folder with the same name, and worktrees share it. A local config can override mapping using longest-prefix matching; doctor output shows the current folder and vault. Local-only Mac files are not thereby visible to a cloud service. Drive is available locally only after the person connects it through the app and the mount is discovered. Installing the cloud plugin does not install local hooks, and installing local hooks does not create remote OAuth access.

Search and source-access limits

Public cloud documentation at revision 1f92e8a states semantic search is unavailable and recall mode auto falls back to keyword matching. This describes cloud behavior, not local parity or live runtime state. Use gram_capabilities and gram_profile to inspect active capabilities; report only returned details. The reviewed sources do not establish identical search or presentation across cloud and local clients.

The cloud package itself does not fetch Slack or Gmail. However, its public plugin configuration includes an example prompt that can ask an assistant to summarize those sources, and server onboarding text may describe broader automatic capture. Telling an assistant to save only after a user request and reviewing its written records are human operating practices, not a product-enforced permission guard. Source availability is not authorization to persist it. Likewise, a local app write permission does not validate the truth or suitability of a record.

Choose by trust boundary

A distributed team needing shared access can choose cloud MCP, inspect OAuth state, discover the vault key and write only to the requested top-level destination. A developer who wants a project brief on each local coding session can install the local integration, ask the person to set app access, keep Thegram open and verify the mapping with doctor. If both are needed, configure both intentionally and identify which path and destination each write used.

Start client configuration from Quickstart, Local setup, or Cloud setup according to the intended path. Read Storage permissions before selecting a mount. The source records below separate internal service provenance from public plugin contracts; check live capabilities rather than treating a static contract as live state.

Source: Public thegram-cloud package

Public repository source at revision 1f92e8a, reviewed for OAuth/MCP package boundaries.

Reference: https://github.com/clab-one/thegram-plugin/tree/1f92e8a

Source: Public thegram-memory package

Public package source at revision 3a1411a, reviewed for hooks, mapping and app proxy.

Reference: https://github.com/clab-one/thegram-mcp/tree/3a1411a

Source: Thegram Vault service implementation

Internal service implementation at revision a193a19; not publicly available.

Source: Official local-agent install instructions

Current public instructions for app permissions and local agent setup.

Reference: https://thegram.one/install/agents.md

Source: Committed cloud plugin contract

Public contract at revision 1f92e8a, including the cloud semantic-search limitation and cursor behavior.

Reference: https://github.com/clab-one/thegram-plugin/blob/1f92e8a/skills/thegram-cloud/references/contracts.md

Knowledge: Keep cloud and local capabilities distinct

Cloud OAuth tools and app-mediated local MCP have different permission and storage paths.

Knowledge: Verify current search capability

Public cloud docs say semantic search is unavailable and auto uses keyword matching; query runtime capabilities and do not infer local parity.

Source and renderer evidence

Canonical source SHA-256: 8050e0ac31bd4d2a2213b0061689e6ec19ccfb6a9514d5999ff3a3270cb8789b
Selected revision: r1 · sha256:1054c51bc1583a2a2d5746c318c47ada869bd2004e2efaee918888a58bc18876
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: 1.gram