# antigravity-supermemory

Persistent memory for **Google Antigravity**, powered by [Supermemory](https://supermemory.ai).
Inspired by [opencode-supermemory](https://github.com/supermemoryai/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.

## 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:**

```sh
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](https://github.com/andylin-hao/antigravity-supermemory/releases/tag/v0.2.1):
[download `antigravity-supermemory-0.2.1.tgz`](https://github.com/andylin-hao/antigravity-supermemory/releases/download/v0.2.1/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:

```jsonc
{
  "apiKey": "sm_your_api_key"
}
```

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

```sh
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:

```sh
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:

```text
◪ 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:

```sh
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:

```sh
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](https://github.com/andylin-hao/antigravity-supermemory/releases)
with the same install flags. Installation is repeatable and refuses to overwrite
locally modified managed files. To remove a global installation:

```sh
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

```sh
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

| Tool | Purpose |
| --- | --- |
| `supermemory` | `mode`: `add`, `search`, `profile`, `list`, `forget`, `help` |
| `supermemory_recall` | Read-only semantic search: `query`, `scope?`, `limit?` |
| `supermemory_context` | Read-only profile + recent project memories; optional `query` |

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:

```json
{"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.

```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"
}
```

| Environment variable | Purpose |
| --- | --- |
| `SUPERMEMORY_API_KEY` | API key |
| `SUPERMEMORY_CONFIG` | Override the global JSONC file path |
| `SUPERMEMORY_API_URL` / `SUPERMEMORY_BASE_URL` | API base URL |
| `SUPERMEMORY_REPO_TAG` | Explicit namespace override |
| `SUPERMEMORY_ISOLATE_WORKTREES` | `true` or `false` |
| `SUPERMEMORY_STATE_DIR` | Local checkpoint directory |

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

```sh
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](https://antigravity.google/docs/plugins/),
[hooks](https://antigravity.google/docs/hooks/),
[MCP](https://antigravity.google/docs/mcp/),
[CLI status line](https://antigravity.google/docs/cli/statusline/),
[rules](https://antigravity.google/docs/rules/).

MIT licensed.