Architecture
Thegram Cloud and Local Agent Integrations: Two Different Architectures
Compare OAuth-backed cloud MCP with app-mediated local MCP, including permissions, storage, current search evidence and client-specific boundaries.
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.
The Vault implementation was inspected internally at revision a193a19 and is not publicly available. Public plugin sources and official install guidance are linked below. Check live capabilities and the current client setup rather than treating a static contract as live state.
Public repository source at revision 1f92e8a, reviewed for OAuth/MCP package boundaries.
https://github.com/clab-one/thegram-plugin/tree/1f92e8aPublic package source at revision 3a1411a, reviewed for hooks, mapping and app proxy.
https://github.com/clab-one/thegram-mcp/tree/3a1411aInternal service implementation at revision a193a19; not publicly available.
Current public instructions for app permissions and local agent setup.
https://thegram.one/install/agents.mdPublic contract at revision 1f92e8a, including the cloud semantic-search limitation and cursor behavior.
https://github.com/clab-one/thegram-plugin/blob/1f92e8a/skills/thegram-cloud/references/contracts.mdCloud OAuth tools and app-mediated local MCP have different permission and storage paths.
Public cloud docs say semantic search is unavailable and auto uses keyword matching; query runtime capabilities and do not infer local parity.
Explicit per-save approval is a human operating practice, not a verified runtime permission guard.
Thegram Cloud and Local Agent Integrations: Two Different Architectures
r0 · Time unknown · Unknown author
Compare OAuth-backed cloud MCP with app-mediated local MCP, including permissions, storage, current search evidence and client-specific boundaries.
Source5
Knowledge3
sha256:d11e3aea970571c9e018975b45510a19094e6ed68eaa77497d07b89e15b37aea@gram 2
doc blog-plugin-architecture
t Thegram Cloud and Local Agent Integrations: Two Different Architectures
d Compare OAuth-backed cloud MCP with app-mediated local MCP, including permissions, storage, current search evidence and client-specific boundaries.
tag architecture
view document
::rich
# 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.
The Vault implementation was inspected internally at revision a193a19 and is not publicly available. Public plugin sources and official install guidance are linked below. Check live capabilities and the current client setup rather than treating a static contract as live state.
[[src-cloud-plugin]]
[[src-local-plugin]]
[[src-vault-service]]
[[src-agent-install]]
[[src-cloud-contract]]
[[knowledge-integration-boundaries]]
[[knowledge-search-limit]]
[[knowledge-consent-limit]]
::end
SRC src-cloud-plugin
t Public thegram-cloud package
d Public repository source at revision 1f92e8a, reviewed for OAuth/MCP package boundaries.
ref https://github.com/clab-one/thegram-plugin/tree/1f92e8a
SRC src-local-plugin
t Public thegram-memory package
d Public package source at revision 3a1411a, reviewed for hooks, mapping and app proxy.
ref https://github.com/clab-one/thegram-mcp/tree/3a1411a
SRC src-vault-service
t Thegram Vault service implementation
d Internal service implementation at revision a193a19; not publicly available.
SRC src-agent-install
t Official local-agent install instructions
d Current public instructions for app permissions and local agent setup.
ref https://thegram.one/install/agents.md
SRC src-cloud-contract
t Committed cloud plugin contract
d Public contract at revision 1f92e8a, including the cloud semantic-search limitation and cursor behavior.
ref https://github.com/clab-one/thegram-plugin/blob/1f92e8a/skills/thegram-cloud/references/contracts.md
K knowledge-integration-boundaries
t Keep cloud and local capabilities distinct
d Cloud OAuth tools and app-mediated local MCP have different permission and storage paths.
source src-cloud-contract
K knowledge-search-limit
t Verify current search capability
d Public cloud docs say semantic search is unavailable and auto uses keyword matching; query runtime capabilities and do not infer local parity.
source src-cloud-contract
K knowledge-consent-limit
t Do not confuse guidance with enforcement
d Explicit per-save approval is a human operating practice, not a verified runtime permission guard.
source src-agent-installSource 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 plugin-architecture.gram source.
- Download file SHA-256
d11e3aea970571c9e018975b45510a19094e6ed68eaa77497d07b89e15b37aea- Renderer
- Existing local Thegram renderer (local Thegram renderer); rendered at build time.
- Renderer document
blog-plugin-architecture- 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.