Guides
Set Up Thegram Memory for Local Coding Agents
Install the local MCP integration and understand its app-level Agent Access boundary before a coding agent reads or writes project memory.
The local thegram-memory integration connects coding agents to project memory maintained by Thegram for Mac. It can brief an agent at session start, expose shared project files through gram_* tools and remind the agent to record durable outcomes. Unlike the cloud integration, it depends on a running Mac app and a person-approved local connection. Installing a plugin is not the same as granting it access to the app or authorizing any particular write.
Requirements and explicit app permission
Use an Apple silicon Mac running macOS 26 or later, Node.js 22 or later on PATH, and a running Thegram app. In the app, open Thegram → Settings… → Agent Connections. The Agent Access control offers Off, Read, and Read and Write. Off disables the integration; Read permits inspection without writes; Read and Write is required for changes. The person at the computer—not the coding agent—must select the intended level, and Connection should report Running. Keep the app open while using local tools because the integration talks to the app’s local MCP connection.
This is an explicit app-level boundary, not a blanket grant to read arbitrary folders, connect Google Drive or copy private material into project memory. A permission switch controls the app-mediated integration; it does not establish that a particular record is accurate or appropriate to save. Make each connector and persistence choice deliberately. The install guide tells the person to set access in the app; an agent should explain the step and wait rather than changing it silently.
Install for your coding host
Use the official agent installation page because host commands and permissions can change. The public thegram-mcp repository contains the local package and its host integrations. For Claude Code, the documented flow adds the marketplace and installs thegram-memory. Codex requires hooks, marketplace installation and a first-run hook trust choice. OMP has marketplace/install commands. OpenCode v2 uses its plugin command; v1 uses an opencode.json entry. Use the current guide for exact syntax instead of copying old commands.
Before a new session, remove any manually configured MCP server named thegram to avoid duplicate registrations. From the project directory, run node "<plugin folder>/dist/thegram-memory.mjs" doctor, replacing the plugin-folder placeholder with the actual installation path, or pass the project directory as the doctor argument. The doctor output should show app connection, vault and the intended project folder. If the app is unreachable, access is Off, or another app connection conflicts, resolve that before trusting a project brief. An installation log alone is not proof that the app is available.
Repository mapping and memory behavior
By default, a Git repository maps to a vault folder with the same name, and worktrees share it. A local projects.json mapping can override a directory prefix; the longest matching prefix wins. For example, a monorepo subtree can map to an existing product memory instead of creating another project folder. Check the doctor output before assuming where the agent will read or write. Google Drive is separate: after the person connects Drive in Thegram, its mount can appear in gram_projects. A local folder is not visible to a cloud agent merely because a local plugin can access it.
At session start, the plugin can provide a project brief; later prompts may include changes made by other writers. A reminder may ask for a durable memory update when work ends with file edits or commits but no record. It is a reminder, not a demand to write on every turn. Useful memory includes verified decisions, shipped changes, incidents, measured results, active tasks and risks. Avoid chatter, guesses, raw logs, credentials and secrets. When a write succeeds, read back the specific record and its placement; do not infer that the visible document changed simply because a record exists.
Example: finish a small migration
Imagine a fictional team chooses to keep a backward-compatible import flag for one release. The agent verifies a compatibility test, updates code and finds a second provider remains unsupported. It can record the accepted decision with its test evidence, add a log event tied to the actual commit, and retain an open task or risk only if the unsupported provider is genuinely unresolved. Place these records in Decisions, Log and Plan and link them to the project. Do not claim completion because code changed; read back the decision, event and remaining work before reporting.
If a checkout maps incorrectly or a writer gets a stale revision, stop before saving. Inspect the mapping and current brief, preserve another writer’s changes, and ask the user when the destination is unclear. Do not create a duplicate file to bypass a mistaken path.
Boundaries and next steps
The local integration is a Node package with hooks, adapters, project mapping and a local MCP proxy; it is not the cloud package. App availability and Agent Access are necessary for local use. Check the current official install guide, package README and policy before applying version-specific advice; tools, mounts and behavior can change. The integration does not turn a local folder into remote storage, nor does a write permission prove the content is safe or true.
Public package source for local setup, doctor, repository mapping and session behavior, inspected at revision 3a1411a.
https://github.com/clab-one/thegram-mcp/blob/3a1411a/README.mdPublic guidance on durable records, safe data and read/write practices, inspected at revision 3a1411a.
https://github.com/clab-one/thegram-mcp/blob/3a1411a/policy.mdPublic tool usage and structured document guidance, inspected at revision 3a1411a.
https://github.com/clab-one/thegram-mcp/blob/3a1411a/skills/thegram-memory/SKILL.mdCurrent public setup instructions and app-level permission steps.
https://thegram.one/install/agents.mdPublic local app-mediated proxy source at revision 3a1411a.
https://github.com/clab-one/thegram-mcp/blob/3a1411a/src/mcp-proxy.tsThe person configures Off, Read, or Read and Write in Thegram; installation does not silently grant permission.
Local plugin tools require the running Mac app and a connection reporting Running.
App Agent Access does not itself approve arbitrary folder reads, Drive connections or persistence of a particular fact.
Set Up Thegram Memory for Local Coding Agents
r0 · Time unknown · Unknown author
Install the local MCP integration and understand its app-level Agent Access boundary before a coding agent reads or writes project memory.
Source5
Knowledge3
sha256:b81a391cd93356803e4294fa585d0207dc3905706c6a462b676c0b34983a54d4@gram 2
doc blog-local-agent-guide
t Set Up Thegram Memory for Local Coding Agents
d Install the local MCP integration and understand its app-level Agent Access boundary before a coding agent reads or writes project memory.
tag guides
view document
::rich
# Set Up Thegram Memory for Local Coding Agents
The local thegram-memory integration connects coding agents to project memory maintained by Thegram for Mac. It can brief an agent at session start, expose shared project files through gram_* tools and remind the agent to record durable outcomes. Unlike the cloud integration, it depends on a running Mac app and a person-approved local connection. Installing a plugin is not the same as granting it access to the app or authorizing any particular write.
## Requirements and explicit app permission
Use an Apple silicon Mac running macOS 26 or later, Node.js 22 or later on PATH, and a running Thegram app. In the app, open Thegram → Settings… → Agent Connections. The Agent Access control offers Off, Read, and Read and Write. Off disables the integration; Read permits inspection without writes; Read and Write is required for changes. The person at the computer—not the coding agent—must select the intended level, and Connection should report Running. Keep the app open while using local tools because the integration talks to the app’s local MCP connection.
This is an explicit app-level boundary, not a blanket grant to read arbitrary folders, connect Google Drive or copy private material into project memory. A permission switch controls the app-mediated integration; it does not establish that a particular record is accurate or appropriate to save. Make each connector and persistence choice deliberately. The install guide tells the person to set access in the app; an agent should explain the step and wait rather than changing it silently.
## Install for your coding host
Use the official agent installation page because host commands and permissions can change. The public thegram-mcp repository contains the local package and its host integrations. For Claude Code, the documented flow adds the marketplace and installs thegram-memory. Codex requires hooks, marketplace installation and a first-run hook trust choice. OMP has marketplace/install commands. OpenCode v2 uses its plugin command; v1 uses an opencode.json entry. Use the current guide for exact syntax instead of copying old commands.
Before a new session, remove any manually configured MCP server named thegram to avoid duplicate registrations. From the project directory, run `node "<plugin folder>/dist/thegram-memory.mjs" doctor`, replacing the plugin-folder placeholder with the actual installation path, or pass the project directory as the doctor argument. The doctor output should show app connection, vault and the intended project folder. If the app is unreachable, access is Off, or another app connection conflicts, resolve that before trusting a project brief. An installation log alone is not proof that the app is available.
## Repository mapping and memory behavior
By default, a Git repository maps to a vault folder with the same name, and worktrees share it. A local projects.json mapping can override a directory prefix; the longest matching prefix wins. For example, a monorepo subtree can map to an existing product memory instead of creating another project folder. Check the doctor output before assuming where the agent will read or write. Google Drive is separate: after the person connects Drive in Thegram, its mount can appear in gram_projects. A local folder is not visible to a cloud agent merely because a local plugin can access it.
At session start, the plugin can provide a project brief; later prompts may include changes made by other writers. A reminder may ask for a durable memory update when work ends with file edits or commits but no record. It is a reminder, not a demand to write on every turn. Useful memory includes verified decisions, shipped changes, incidents, measured results, active tasks and risks. Avoid chatter, guesses, raw logs, credentials and secrets. When a write succeeds, read back the specific record and its placement; do not infer that the visible document changed simply because a record exists.
## Example: finish a small migration
Imagine a fictional team chooses to keep a backward-compatible import flag for one release. The agent verifies a compatibility test, updates code and finds a second provider remains unsupported. It can record the accepted decision with its test evidence, add a log event tied to the actual commit, and retain an open task or risk only if the unsupported provider is genuinely unresolved. Place these records in Decisions, Log and Plan and link them to the project. Do not claim completion because code changed; read back the decision, event and remaining work before reporting.
If a checkout maps incorrectly or a writer gets a stale revision, stop before saving. Inspect the mapping and current brief, preserve another writer’s changes, and ask the user when the destination is unclear. Do not create a duplicate file to bypass a mistaken path.
## Boundaries and next steps
The local integration is a Node package with hooks, adapters, project mapping and a local MCP proxy; it is not the cloud package. App availability and Agent Access are necessary for local use. Check the current official install guide, package README and policy before applying version-specific advice; tools, mounts and behavior can change. The integration does not turn a local folder into remote storage, nor does a write permission prove the content is safe or true.
[[src-memory-readme]]
[[src-memory-policy]]
[[src-memory-skill]]
[[src-install-agents]]
[[src-memory-proxy]]
[[knowledge-local-permission]]
[[knowledge-local-runtime]]
[[knowledge-local-scope]]
::end
SRC src-memory-readme
t thegram-memory README
d Public package source for local setup, doctor, repository mapping and session behavior, inspected at revision 3a1411a.
ref https://github.com/clab-one/thegram-mcp/blob/3a1411a/README.md
SRC src-memory-policy
t Local project memory policy
d Public guidance on durable records, safe data and read/write practices, inspected at revision 3a1411a.
ref https://github.com/clab-one/thegram-mcp/blob/3a1411a/policy.md
SRC src-memory-skill
t Local memory skill reference
d Public tool usage and structured document guidance, inspected at revision 3a1411a.
ref https://github.com/clab-one/thegram-mcp/blob/3a1411a/skills/thegram-memory/SKILL.md
SRC src-install-agents
t Official coding-agent installation page
d Current public setup instructions and app-level permission steps.
ref https://thegram.one/install/agents.md
SRC src-memory-proxy
t Local app-mediated MCP proxy
d Public local app-mediated proxy source at revision 3a1411a.
ref https://github.com/clab-one/thegram-mcp/blob/3a1411a/src/mcp-proxy.ts
K knowledge-local-permission
t Keep Agent Access intentional
d The person configures Off, Read, or Read and Write in Thegram; installation does not silently grant permission.
source src-install-agents
K knowledge-local-runtime
t The local app is a runtime dependency
d Local plugin tools require the running Mac app and a connection reporting Running.
source src-memory-readme
K knowledge-local-scope
t Separate folder access from app permission
d App Agent Access does not itself approve arbitrary folder reads, Drive connections or persistence of a particular fact.
source src-memory-policySource 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 local-agent-guide.gram source.
- Download file SHA-256
b81a391cd93356803e4294fa585d0207dc3905706c6a462b676c0b34983a54d4- Renderer
- Existing local Thegram renderer (local Thegram renderer); rendered at build time.
- Renderer document
blog-local-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.