# Connect a coding agent to Thegram

For Claude Code, Codex, OpenCode and OMP. The `thegram-memory` plugin (https://github.com/thegram-one/thegram-mcp) connects directly to Thegram Cloud MCP, injects this project's memory and reminds the agent to record durable outcomes. No DMG, Mac app, desktop socket or running desktop process is required. ChatGPT and Claude's cloud integrations use OAuth separately.

You are the agent. Run the applicable checks and installation commands yourself. Ask the person only for login, permissions and secret input. Never ask them to paste an API key into chat, put it in a command argument, or commit it to a repository. Do not copy existing local memory into Cloud without authorization.

## 1. Check the runtime

`node --version` must show Node.js 22 or later. If it is unavailable, ask the person to install the current LTS from https://nodejs.org using their normal package manager. Do not install a desktop application.

## 2. Issue an API key

Ask the person to open https://vault.thegram.one/, sign in and open **Settings → Agents → API keys**. Create a named key, select the intended Cloud vault and grant only the required permissions. Writing project memory requires write access. Copy the secret once; the list will not reveal it again. Google Drive requires a separate connection and explicit permission.

Do not read credentials from unrelated agent installations, browser profiles or desktop-app files.

## 3. Install the plugin

Run the block for the current agent. Remove an old manually registered `thegram` MCP binding so only this plugin supplies it; preserve unrelated servers and plugins.

Claude Code:

```sh
claude mcp remove --scope user thegram >/dev/null 2>&1 || true
claude plugin marketplace add thegram-one/thegram-mcp || claude plugin marketplace update thegram-memory
claude plugin install thegram-memory@thegram-memory
claude plugin update thegram-memory@thegram-memory || true
```

Codex:

```sh
codex mcp remove thegram >/dev/null 2>&1 || true
codex plugin remove thegram@thegram-local >/dev/null 2>&1 || true
codex features enable hooks
codex plugin marketplace add thegram-one/thegram-mcp || codex plugin marketplace upgrade
codex plugin add thegram-memory@thegram-memory
```

Tell the person that the next Codex run may ask whether to trust the plugin hooks. Explain their purpose before they choose **Trust all and continue**.

OpenCode:

```sh
opencode plugin add github:thegram-one/thegram-mcp
```

For OpenCode v1, add `github:thegram-one/thegram-mcp` to the `plugin` array in its user configuration instead.

OMP:

```sh
omp plugin marketplace add thegram-one/thegram-mcp || true
omp plugin install thegram-memory@thegram-memory
omp plugin marketplace update thegram-memory
omp plugin upgrade thegram-memory@thegram-memory --scope user
```

The current coding-agent package is **3.4.0**. For an existing OMP installation, the upgrade target is the full marketplace ID `thegram-memory@thegram-memory`; a bare package name is not valid for this command. This updates the plugin's skill and adapter while retaining the existing private connection configuration. Start a new agent session afterward; installation does not restart current sessions.

## 4. Connect privately

Locate `dist/thegram-memory.mjs` in the installed plugin, version 3 or later. From the project directory, give the person this exact command with the installed path filled in, in their own terminal:

```sh
node <installed-plugin>/dist/thegram-memory.mjs connect
```

The prompt hides input. The person pastes the API key there, not into the agent conversation. The CLI verifies access and selects a Cloud vault; when several are accessible it asks which one to use. For managed automation, provide `THEGRAM_API_KEY` and `THEGRAM_MCP_MOUNT` through the host's secret environment instead. Never print or capture those values.

The CLI stores `~/.config/thegram-memory/connection.json` privately (POSIX directory `0700`, file `0600`). `XDG_CONFIG_HOME` changes the config root. Do not change this file to point an existing key at another server.

Then run:

```sh
node <installed-plugin>/dist/thegram-memory.mjs doctor
```

Exit code 0 reports the Cloud endpoint, accessible mounts and exact project document. Exit code 1 is a connection, permission or configuration failure; fix that cause, never fall back to a local app or a different mount. An invalid, expired or revoked key must be replaced through Settings → Agents.

## 5. Finish

Start a new agent session. Its Git repository maps to `@mounts/<selected-vault-id>/<repository>.gram`, including across worktrees. Explicit overrides in `~/.config/thegram-memory/projects.json` must be exact top-level Cloud document paths. Old desktop-folder mappings are not compatible and local-only documents are not automatically migrated.

Verify `gram_projects`, then `gram_brief {path}` for the configured memory document if it exists. Do not create test records in the person's real memory merely to prove connection. When the first authorized durable outcome occurs, create the exact configured document if needed.

Tell the person which vault and access level are connected, whether a memory document already exists, and that API-key revocation in Thegram disables future use. A first prompt is: “What does Thegram remember about this project?”

## Shared skill and verified downloads

The same eight-file workflow is supplied by coding-agent **thegram-memory 3.4.0** and cloud **thegram-cloud 2.3.0**, with only the skill frontmatter name differing. Classify atomic facts by meaning: commits/PRs/reports are provenance; reuse tasks, components and metrics, keep proposed decisions and incomplete work at their sourced states, and reserve events for meaningful dated occurrences. Routine image pins can remain source coverage. Do not invent task lifecycles, observations or old revision activity to populate widgets. Scheduled automations (research digests, monitors, collected logs) record one run per execution, keep each found item once with its link, time, source and topic, and tag the things they watch, so the research, monitoring and collected-log dashboards show what is new, the runs and each target. Agents keep each piece of work as one task naming the agent and the repository, move its status with the work and record each PR, merge, release or deployment as one step of that task, so the AI work board shows who is doing what, how the work went and what waits on you.

Every document follows one record vocabulary, so each status has one meaning everywhere: a mitigated risk or a proposed decision stays open, a resolved risk or an accepted decision is done, and superseded or rejected decisions and accepted or closed risks are closed. A new document takes no template. Closing a record rewrites its description to the outcome and links the resolving evidence as `related`; `ref` holds only links other people can open.

Widgets need actual record types, statuses, dates and relationships: goal progress uses task→goal `part-of`; metric trends need comparable observations on the same ID and loaded history. Team/presence/sync displays need runtime capabilities. Saved-layout readiness does not prove useful rendering or live health. Authorization, source attribution and fresh readback still apply.

- Coding-agent source package: https://thegram.one/download/releases/thegram-memory-3.4.0.zip
- Portable cloud plugin: https://thegram.one/download/releases/thegram-cloud-2.3.0.zip
- Source commits, archive SHA-256 and per-file skill hashes: https://thegram.one/download/releases/manifest.json

Use the host's normal marketplace/plugin installer. A ZIP download alone does not activate a skill. Existing private App-backed ChatGPT plugins must preserve their App binding, interface and connection; do not replace them with the portable public package. These downloads are plugin/skill assets, not a desktop app.

Help: support@thegram.one · Human guide: https://thegram.one/install/#coding-agents