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 project recall on each new substantive user prompt. Recall requests run concurrently with a three-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.

• 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: engram

Install with npx

Requires Node.js 22+, npm, a Supermemory API key, and Antigravity. The package has not been published to npm yet. Use the local release tarball now:

npx --yes ./antigravity-supermemory-0.1.0.tgz install --workspace /absolute/path/to/your/project

For all workspaces, replace --workspace /absolute/path/to/your/project with --global. Then configure your API key and restart Antigravity.

Once this package is published to npm, the equivalent short command will be:

npx --yes antigravity-supermemory@latest install --workspace /absolute/path/to/your/project
# Or: npx --yes antigravity-supermemory@latest install --global

Installation copies a standalone runtime into the managed plugin directory. Antigravity can continue using it after npx's cache is cleared or the original checkout/tarball is removed. Node.js must remain at the installed executable path; rerun installation after changing your Node installation.

Install from this checkout

git clone https://github.com/andylin-hao/antigravity-supermemory.git
cd antigravity-supermemory
npm ci
npm run build

# Install for a project you open in Antigravity:
node dist/cli.js install --workspace /absolute/path/to/your/project

This creates .agents/plugins/supermemory/ in the target project, with a manifest, MCP configuration, hooks, rule, skill, and standalone runtime. Generated commands use absolute paths to Node and the installed runtime, with no dependency on this checkout's node_modules.

For all workspaces instead:

node dist/cli.js install --global

This installs into ~/.gemini/config/plugins/supermemory/. 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.

Configure the API key

Set SUPERMEMORY_API_KEY in the environment of the Antigravity process, or create the global config file printed by:

npx --yes ./antigravity-supermemory-0.1.0.tgz config-path

Default: ~/.config/antigravity-supermemory/config.jsonc

{
  "apiKey": "sm_your_api_key"
}

The global file is convenient for GUI launches that do not inherit terminal environment variables. Keep it outside your repository and restrict its file permissions (for example, chmod 600 on Unix).

Reload Antigravity's customizations/MCP servers or restart the application. Check the connection with:

npx --yes ./antigravity-supermemory-0.1.0.tgz status --workspace /absolute/path/to/your/project

Then 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.

Older Antigravity IDE versions

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

node dist/cli.js 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, specify it:

node dist/cli.js install --legacy --workspace /absolute/path/to/project \
  --mcp-config /absolute/path/to/mcp_config.json

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, rerun the npx install command with the new release tarball (or @latest after publication). From a checkout, run npm ci, npm run build, and the same install command. Installation is repeatable and refuses to overwrite locally modified managed files. Uninstall uses the same scope/mode flags:

npx --yes ./antigravity-supermemory-0.1.0.tgz uninstall --workspace /absolute/path/to/project

From the checkout:

node dist/cli.js uninstall --workspace /absolute/path/to/project
# Or: node dist/cli.js uninstall --global
# Or: node dist/cli.js uninstall --legacy --workspace /absolute/path/to/project

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.

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. user means personal facts within the current repository, matching the current OpenCode plugin, not a global profile shared across unrelated repositories.

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": 3000,
  "requestTimeoutMs": 8000,
  "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.

• 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, browser OAuth flow, or OpenCode-style status footer in this release.

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, rules.

MIT licensed.