antigravity-supermemory

Persistent memory for Google Antigravity, powered by Supermemory. Inspired by opencode-supermemory. This is an independent integration, using Antigravity's native plugin, hook, skill, and MCP interfaces.

Features

• Automatic recall: profile and recent project facts on the first model call; semantic recall across project and personal repository memories on each new substantive user prompt. Recall requests run concurrently with a ten-second timeout each and no automatic retries.

• Automatic capture: at an idle Stop, save new user/assistant turns with stable document IDs and persistent checkpoints. Repeated hooks skip acknowledged saves.

• Memory tools: add, search, profile, list, and forget; plus read-only recall and session-context tools.

• Visible CLI activity: a conversation-scoped status line shows recall counts, save progress, and failures. MCP results include a readable activity summary.

• Remember requests: hooks and an always-on rule remind the agent to store the fact when you say “remember”, “save this”, or “don't forget”.

• Codebase knowledge: a supermemory-init skill explores and remembers build commands, architecture, and conventions.

• Privacy: remove <private>...</private> regions, including nested and unclosed regions, before uploads and searches. Capture excludes tool output, reasoning, and recognized synthetic/system messages.

• Shared repository identity: the same canonical namespace and sm_scope metadata convention as current OpenCode Supermemory.

Related MCP server: Recall Select

Quick start

Requires Node.js 22+, npm, a Supermemory API key, and Antigravity.

1. Install the plugin

Run this command to install for all workspaces. npx downloads the packaged GitHub release automatically:

npx --yes https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/antigravity-supermemory-0.2.1.tgz install --global

The package is available in the Assets section of the v0.2.1 release: download antigravity-supermemory-0.2.1.tgz. If you download it manually, run npx --yes ./antigravity-supermemory-0.2.1.tgz install --global from the download directory. Distribution is through GitHub Releases; npm registry publication is still pending.

For a single project, replace --global with --workspace /absolute/path/to/your/project.

• Global installation: ~/.gemini/config/plugins/supermemory/

• Workspace installation: <project>/.agents/plugins/supermemory/

The installer includes the manifest, MCP server, hooks, rule, skill, and a standalone runtime. It continues working after npx's cache or the downloaded tarball is removed. Rerun installation after changing your Node executable path.

2. Configure your API key

Create ~/.config/antigravity-supermemory/config.jsonc (including its parent directory) and add your Supermemory key:

{
  "apiKey": "sm_your_api_key"
}

~ means your user home directory (for example, C:\Users\YourName on Windows). For the exact path, run:

npx --yes https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/antigravity-supermemory-0.2.1.tgz config-path

You can also set SUPERMEMORY_API_KEY in the environment of the Antigravity process. The config file is convenient for GUI launches that do not inherit terminal variables. Keep it outside your repository and restrict its permissions (for example, chmod 600 on Unix).

3. Restart and verify

Restart Antigravity or reload its customizations/MCP servers. In a new chat, ask:

Call supermemory_context for the current workspace and report whether it succeeds.

A successful response, even with no memories, confirms the plugin is connected. You can also check API connectivity from your terminal:

npx --yes https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/antigravity-supermemory-0.2.1.tgz status --workspace /absolute/path/to/your/project

To try saving a memory, ask Antigravity:

Remember that this project uses npm and tests run with npm test.

In another conversation:

What package manager and test command does this project use?

Supermemory processes uploads asynchronously; queued documents can take minutes to become searchable memories.

Workspace selection

Global MCP calls must include an absolute workspace path; the bundled rule tells the agent to supply it. Hooks use the single workspacePaths entry in Antigravity's payload. For multi-root sessions, automatic hooks skip ambiguous workspaces; tools still work with an explicit path. Choose one installation route per workspace to avoid duplicate plugin components.

Visible activity in agy CLI

A global install enables a Supermemory line at the bottom of agy's prompt panel. Restart agy after installing or updating. For example:

◪ supermemory · recalling…
◪ supermemory · recalled 3 memories · saving…
◪ supermemory · recalled 3 memories · saved 1 document (queued)

The counts come from completed hook requests in the current conversation: recall counts unique returned memories/profile facts, and saves count documents accepted during the last capture run. queued means extraction is asynchronous. The display also distinguishes recall unavailable (timeout), partial results, interrupted requests, disabled hooks, and a missing key. It refreshes when agy updates its agent state, so very brief in-progress states may not be visible.

The installer configures statusLine in ~/.gemini/antigravity-cli/settings.json, keeping the built-in line by default. An existing custom command is rendered first; uninstall restores the original configuration. Add --no-statusline to install --global to opt out (or restore the previous line). Workspace-only installs do not change global CLI settings.

Explicit MCP tool results also include an activity field, such as supermemory recalled 3 memories. These appear in tool output rather than the hook status line. The custom footer is an agy CLI feature; IDE/headless clients can still show the MCP activity summaries.

Proxy connections

All SDK requests automatically use the proxy environment inherited from the process that launches them: agy for hooks/MCP, or your shell for npx … status. This works across supported Node 22/24 versions without --use-env-proxy:

• http_proxy / HTTP_PROXY: HTTP proxy URL; also the fallback for HTTPS requests.

• https_proxy / HTTPS_PROXY: proxy for HTTPS requests, taking precedence over the HTTP proxy. An http:// proxy URL is normal for HTTPS CONNECT tunneling.

• no_proxy / NO_PROXY: hosts that connect directly instead.

• Lowercase variables take precedence over uppercase variables.

For example, in the shell where you start agy:

export http_proxy=http://127.0.0.1:10809
export https_proxy="$http_proxy"
agy

Proxy URLs are read at runtime, never copied into the installed plugin. Restart agy after changing its environment or upgrading the plugin. Existing processes cannot inherit changes made later in another shell.

recalled 0 memories (partial: timeout) means some requests timed out; it does not mean the repository has no saved memories. Defaults allow 10 seconds per recall request and 30 seconds for save/tool requests. If needed, set recallTimeoutMs (up to 20000) and requestTimeoutMs (up to 60000) in the JSONC config. Hook watchdogs leave room for these budgets; capture shares one request budget across its uploads and resumes remaining chunks at a later idle Stop.

Older Antigravity IDE versions

If your IDE supports MCP but not native plugins/hooks, use:

npx --yes https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/antigravity-supermemory-0.2.1.tgz install --legacy --workspace /absolute/path/to/your/project

The installer merges a project-specific server into ~/.gemini/antigravity/mcp_config.json and adds .agent/rules/supermemory.md and .agent/workflows/supermemory-init.md. Existing servers and JSONC comments are preserved. If MCP Servers → View raw config shows another path, append --mcp-config /absolute/path/to/mcp_config.json to the command.

This mode uses agent-driven recall and saving through the rule. It does not automatically capture turns or inject context through hooks. Run /supermemory-init to index project knowledge using the workflow.

Update and uninstall

To update, use the packaged .tgz URL from the latest GitHub release with the same install flags. Installation is repeatable and refuses to overwrite locally modified managed files. To remove a global installation:

npx --yes https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/antigravity-supermemory-0.2.1.tgz uninstall --global

For a workspace installation, replace --global with --workspace /absolute/path/to/project. For legacy mode, also add --legacy.

Only unmodified managed files (including the runtime) and the matching legacy MCP entry are removed. Unrelated configuration, remote memories, API credentials, and capture checkpoints are retained. If a managed file was edited, reconcile it before rerunning.

Install from source

git clone https://github.com/andylin-hao/antigravity-supermemory.git
cd antigravity-supermemory
npm ci
npm run build
node dist/cli.js install --global

All CLI commands above are also available as node dist/cli.js <command> from the checkout. To build your own distributable tarball, run npm pack; it creates antigravity-supermemory-0.2.1.tgz in the checkout root.

Tools

All tools accept workspace: an absolute project directory. It is optional when the server was started with --workspace (as in a workspace installation). Antigravity may prefix tool names with the plugin/server name.

supermemory examples:

{"mode":"add","content":"Tests run with npm test","type":"project-config","scope":"project"}
{"mode":"search","query":"test command","scope":"project"}
{"mode":"profile"}
{"mode":"list","scope":"project","limit":10}
{"mode":"forget","memoryId":"mem_from_search_or_list","scope":"project"}

Scopes: project is the default for add, list, and forget. user means personal facts within the current repository, matching the current OpenCode plugin, not a global profile shared across unrelated repositories. all is the default for search and supermemory_recall, searching across both project and user memories in the repository.

Types: project-config, architecture, error-solution, preference, learned-pattern, conversation.

IDs: add returns an ingested document ID. search and list return extracted memory IDs. forget checks the memory's namespace and scope before removing it from normal recall; it preserves Supermemory audit history and source documents. This tool is not a permanent document-erasure API.

Configuration

All options are optional. Environment variables take precedence over JSONC.

{
  "apiKey": "sm_...",
  "baseUrl": "https://api.supermemory.ai",
  "recallMode": "direct", // direct | advisory | off
  "captureEnabled": true,
  "injectProfile": true,
  "maxMemories": 5,
  "maxProfileItems": 5,
  "similarityThreshold": 0.55,
  "recallTimeoutMs": 10000,
  "requestTimeoutMs": 30000,
  "maxContextChars": 8000,
  "isolateWorktrees": false,
  // "projectContainerTag": "my_explicit_namespace",
  // "stateDir": "/absolute/path/to/local/checkpoints"
}

The client uses the official Supermemory v5 SDK, including ns/... routes. Custom servers must implement that API. There is no legacy API fallback or automatic rerouting to hosted Supermemory.

Scoping and compatibility

Default namespace: repo_<sanitized-repository-name>__<16-char-sha256>. The hash uses normalized Git origin, or the repository's real path if there is no origin. SSH and HTTPS origins share an identity; different remotes remain isolated. Worktrees share the main repository unless isolation is enabled. Metadata sm_scope is project or personal.

Current OpenCode memories using this convention are shared automatically when both integrations use the same account/API endpoint. Custom namespaces require the same explicit override. Historical opencode_project_*/opencode_user_* containers and other agents' config overrides are not automatically discovered.

Hook behavior and limitations

• PreInvocation reads the transcript path supplied by Antigravity and injects an ephemeralMessage. Repeated model/tool-loop calls for the same user prompt do not repeat searches. off disables hook recall, not explicit MCP tools.

• Stop acts as a turn boundary, not session shutdown. Only fullyIdle: true permits capture. New turns are uploaded individually; raw tool output and thinking are not collected. Disable this with captureEnabled: false.

• Transcript extraction supports current USER_INPUT/PLANNER_RESPONSE text records and explicit role/content records. It reads only the supplied file, not private databases or other conversation directories. Unknown records and incomplete JSON lines are skipped; missing, oversized (>20 MiB), or changed transcript formats can prevent automatic recall/capture. MCP tools still work.

• Capture checkpoints contain hashes, not conversation text, under ~/.cache/antigravity-supermemory/. File leases protect simultaneous hooks; checkpoints advance after acknowledged uploads. Failed saves can retry on a later idle Stop. Stable IDs reduce duplication but do not guarantee exactly-once processing/billing after an ambiguous response. Removing checkpoints may replay old turns; changing transcript indices can change capture identity.

• Status-line files under the same cache's activity/ directory store only phase, count, timestamp, and an optional failure category (timeout, network, etc.), keyed by hashed account/endpoint/conversation identity. They do not store prompts, recalled text, credentials, or API error bodies.

• Hook errors fail open, print sanitized diagnostics to stderr, and produce valid JSON. Capture has a bounded per-hook budget; a large backlog may require later Stop events. Pending captures cannot be flushed after Antigravity is killed.

• Rules guide model behavior; they cannot guarantee that an explicit memory tool is called. There is no native compaction interception or browser OAuth flow.

Development and verification

npm ci
npm run check
agy plugin validate plugin --strict --json
npm pack

Tests exercise real SDK requests against a local mock HTTP service, a real stdio MCP client/server handshake using the installed standalone runtime, hook timeouts, capture retries/concurrency, privacy, repository scoping, and non-destructive installation/uninstallation. They need no API key and do not contact hosted Supermemory. Antigravity CLI 1.4.0's validator accepts the bundled plugin. Full IDE operation with a live Supermemory account requires a manual smoke test after configuration. The npx tarball install has also been verified with hooks and MCP still working after deleting the npx cache and the source tarball.

For portable native-plugin distribution, install this npm package globally from an npm pack tarball and use agy plugin install /path/to/checkout/plugin. The checked-in template invokes antigravity-supermemory on PATH; the recommended CLI installer replaces these with absolute commands.

References: plugins, hooks, MCP, CLI status line, rules.

MIT licensed.