---
title: "ZeroDB Claude Code Plugin"
description: "Persistent cross-session memory for Claude Code — like CLAUDE.md but it writes itself and gets smarter."
canonical: "https://docs.ainative.studio/docs/guides/claude-plugin"
last-updated: "2026-10-22T17:48:46.689Z"
---

# ZeroDB Claude Code Plugin

Source: https://docs.ainative.studio/docs/guides/claude-plugin

> Persistent cross-session memory for Claude Code — like CLAUDE.md but it writes itself and gets smarter.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## ZeroDB Claude Code Plugin

Persistent, searchable memory for Claude Code across every session. Claude remembers your architecture decisions, debugging breakthroughs, conventions, and in-progress work — automatically.

> **Like CLAUDE.md but it writes itself and gets smarter.**

---

## Introduction

Claude Code sessions are stateless. Every session starts from scratch: you re-explain your stack, re-describe the bug from last week, re-correct the same wrong assumptions. On a large codebase, that re-orientation costs 5–15 minutes every time.

The ZeroDB Claude Code Plugin solves this by giving Claude persistent, semantic memory across sessions:

- **At session start** — Claude automatically recalls relevant memories from past sessions and injects them as context before your first message.
- **At session end** — Claude extracts key facts from the session (decisions made, bugs found, conventions established) and stores them in ZeroDB.
- **On demand** — Use `/remember`, `/recall`, and `/forget` slash commands to manually manage what Claude knows.

Memory is stored in your ZeroDB account — vector-indexed, semantically searchable, and scoped per project (detected from your git remote). It compounds: the longer you use it, the smarter Claude gets in your codebase.

:::tip What gets stored
Facts, decisions, and patterns — not file contents or secrets. Example stored memories:
- `"Uses PgBouncer on port 6432, never connect to 5432 directly"`
- `"Sarah Chen owns the payments module — never refactor without her sign-off"`
- `"Llama models route through DigitalOcean/Cerebras — Meta API was retired"`
:::

---

## Installation

<Tabs>
<TabItem value="official" label="Official Marketplace" default>

```shell
## From the official Claude Code plugin marketplace
/plugin install zerodb-memory@claude-plugins-official
```

</TabItem>
<TabItem value="ainative" label="AINative Marketplace">

```shell
## Add AINative's plugin marketplace (always ships latest)
/plugin marketplace add github:AINative-Studio/claude-plugins

## Then install
/plugin install zerodb-memory@ainative-plugins
```

</TabItem>
<TabItem value="github" label="Direct from GitHub">

```shell
## Install directly from the plugin repo — no marketplace needed
/plugin install github:AINative-Studio/zerodb-claude-plugin
```

</TabItem>
</Tabs>

After installation, the plugin automatically configures the `ainative-zerodb-memory-mcp` MCP server in your Claude Code settings. No manual `~/.claude/settings.json` editing required.

---

## Authentication

The plugin reads your ZeroDB API key from the `ZERODB_API_KEY` environment variable.

### 1. Get your API key

Sign up at [ainative.studio/signup?ref=claude-plugin](https://ainative.studio/signup?ref=claude-plugin) — new accounts receive **500 free credits** (approximately 20 sessions). No credit card required.

Your API key is available in the ZeroDB dashboard under **Settings → API Keys**.

### 2. Set the environment variable

<Tabs>
<TabItem value="zsh" label="Zsh (~/.zshrc)" default>

```bash
echo 'export ZERODB_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
```

</TabItem>
<TabItem value="bash" label="Bash (~/.bashrc)">

```bash
echo 'export ZERODB_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

</TabItem>
<TabItem value="dotenv" label=".env (project root)">

```bash
## .env at your project root (do NOT commit this file)
ZERODB_API_KEY=your-api-key-here
ZERODB_PROJECT_ID=your-project-id   # optional — auto-detected from git remote
```

</TabItem>
</Tabs>

:::warning Never commit your API key
Add `.env` to your `.gitignore`. Use shell profile exports or a secrets manager for production environments.
:::

### 3. Verify

```shell
## In a new Claude Code session — you should see:
## [ZeroDB Memory] Connected · 0 memories for this project
```

---

## How It Works

### Session Start — Auto-Recall

When you open a Claude Code session, the plugin's `PreToolUse` hook fires before Claude responds to your first message. It:

1. Detects your project from `git remote get-url origin` (normalized to `org/repo` format).
2. Calls `zerodb_get_context` to fetch memories scoped to that project.
3. Runs a semantic search against your opening message to rank memories by relevance.
4. Injects the top memories as context before Claude's first response.

You'll see a brief status message at the top of the session:

```
[ZeroDB Memory] Recalled 7 memories for ainative-studio/core:
• Architecture: Uses PgBouncer on port 6432, never connect to 5432 directly
• Convention: All API endpoints require Refs #<issue> in commits
• Bug: Llama models route through DigitalOcean/Cerebras — Meta API retired Jun 2026
• In-Progress: Billing sprint — 3 paying customers, fixing invoice generation
• Correction: Don't use alembic upgrade head in production, use sync-production-schema.py
```

:::note First session
Your first session will recall 0 memories — that's expected. By the end of that session, auto-persist will store the first batch of memories for future recall.
:::

### Session End — Auto-Persist

When your session ends (or after significant tool use), the plugin's `Stop` hook prompts Claude to review the conversation and extract key facts. Claude then stores each fact as a separate memory via `zerodb_store_memory`.

**What Claude extracts and stores:**

| Category | Examples |
|---|---|
| Architecture decisions | `"Switched from Celery to Temporal for async workflows"` |
| Bugs and root causes | `"Kong http-log plugin retries cause 503 storms — disable on high traffic"` |
| Conventions established | `"Always use double quotes in bash commands with spaces in paths"` |
| File/module ownership | `"billing module owned by Sarah Chen, infra owned by Bob"` |
| In-progress work | `"Working on Phase 2 SSO — 21 endpoints done, 3 remaining"` |
| Corrections | `"DB pool limit is 20 per instance, not 10 as previously assumed"` |

**What is never stored:**

- API keys, passwords, tokens, or any credentials
- Raw file contents or code
- PII (emails, phone numbers, addresses)
- Information you explicitly mark with `[private]`

### Project Scoping

Memories are scoped to the git remote of your current working directory. If you open Claude Code in two different repos, they get separate memory namespaces. You'll never get memories from Project A leaking into Project B.

---

## Slash Commands Reference

### `/remember`

Manually store a memory. Claude parses your text, enhances it for searchability, and stores it with appropriate tags.

```shell
/remember The payments module is owned by Sarah Chen — never refactor without her sign-off
/remember We use Temporal for all async workflows, not Celery (Celery is legacy, being migrated out)
/remember Railway internal DNS doesn't work from Kong — always use the public URL
/remember Database pool limit is 20 connections per instance (10 base + 10 overflow)
```

Claude confirms what was stored:

```
Stored: "Payments module owned by Sarah Chen — requires her sign-off before refactoring"
Tagged: ownership, payments, team
```

### `/recall`

Search your memories and surface relevant results in the current conversation.

```shell
/recall how do we handle auth tokens
/recall what did we decide about the database schema
/recall which module does Sarah own
/recall what's the status of the billing sprint
```

Results are ranked by semantic similarity to your query, not by recency.

### `/forget`

Remove memories that are outdated or incorrect. Claude shows you matching memories and asks for confirmation before deleting.

```shell
/forget old staging URL
/forget the note about Celery migration — it's complete now
/forget incorrect database port note
```

### `/memory`

The main memory management command. Supports the following subcommands:

| Subcommand | What it does |
|---|---|
| `/memory list` | Paginated list of all memories for the current project |
| `/memory stats` | Count, storage used, credits consumed, last sync time |
| `/memory export` | Export memories as JSON (default) or Markdown |
| `/memory export --format claudemd` | Generate a `CLAUDE.md` from your memories |
| `/memory autopersist on\|off\|review` | Control auto-persist behavior |
| `/memory autorecall on\|off` | Enable or disable auto-recall at session start |
| `/memory clear` | Wipe all memories for the current project (requires confirmation) |

#### Examples

```shell
## Check memory stats for the current project
/memory stats
## → 31 memories · 4.2 KB · last synced 2026-04-23 · 847 credits used

## See all stored memories
/memory list

## Export as JSON for backup
/memory export

## Switch auto-persist to review mode (Claude shows you memories before saving)
/memory autopersist review

## Turn off auto-recall temporarily
/memory autorecall off
```

---

## Configuration

All configuration is done via environment variables. Set them in your shell profile or a `.env` file at the project root.

| Variable | Default | Description |
|---|---|---|
| `ZERODB_API_KEY` | — | **Required.** Your ZeroDB API key. Get one at [ainative.studio/signup](https://ainative.studio/signup?ref=claude-plugin). |
| `ZERODB_PROJECT_ID` | Auto-detected | ZeroDB project ID. Auto-detected from your git remote URL. Override if you want to point multiple repos at the same memory namespace. |
| `ZERODB_AUTOPERSIST` | `on` | Auto-persist mode. `on` = save automatically, `off` = never auto-save, `review` = show memories before saving. |
| `ZERODB_AUTORECALL` | `on` | Auto-recall at session start. `on` = inject memories automatically, `off` = manual `/recall` only. |

:::tip Teams: point multiple devs at the same project
Set `ZERODB_PROJECT_ID` to the same value across your team's machines to share a memory namespace. Claude will know about architecture decisions and ownership patterns regardless of who made them.
:::

---

## CLAUDE.md Export

The plugin can generate or update a `CLAUDE.md` from your accumulated memories:

```shell
/memory export --format claudemd
```

### Generate vs. Update

- **Generate** (no existing `CLAUDE.md`): Creates a new `CLAUDE.md` with sections derived from memory types.
- **Update** (existing `CLAUDE.md`): Merges new memories into the existing file, preserving your hand-written sections. Memories are appended under a `## ZeroDB Memory` section that the plugin manages.

### Example Output

```markdown
## Project Memory — ainative-studio/core

_Generated by ZeroDB Claude Code Plugin on 2026-04-24. Do not edit the ZeroDB Memory section manually._

## Architecture

- Uses PgBouncer on port 6432 for database connections — never connect directly to port 5432
- Kong API gateway upstream must use public Railway URL — internal DNS resolution fails from Kong
- DB pool is 20 connections per instance (10 base + 10 overflow)

## Conventions

- All commits must reference a GitHub issue: `Refs #123` or `Closes #123`
- Never run `alembic upgrade head` in production — use `scripts/sync-production-schema.py`
- Branch naming: `[type]/[issue-number]-[slug]`

## Team

- Payments module: Sarah Chen (sign-off required before refactoring)
- Infrastructure: Bob (owns Railway config, Kong, and DB provisioning)

## Active Work

- Billing sprint: 3 paying customers onboarded, invoice generation fix in progress
- Phase 2 SSO: 21 endpoints shipped, 3 remaining (audit log, session revocation, SCIM)
```

---

## Pricing

Memory operations bill to your ZeroDB account in credits.

| Operation | Credits |
|---|---|
| Store memory | 1 credit |
| Semantic search (`/recall`) | 2 credits |
| Get context bundle (auto-recall) | 3 credits |
| Embed text | 1 credit |

**Average session cost:** ~25 credits (10 stores + 5 recalls at session start and end).

At $0.01/credit, daily use costs approximately $0.25/session or $5–7/month. New accounts start with **500 free credits** — enough for ~20 sessions with no credit card required.

For heavier use, plugin credits count toward your existing ZeroDB/AINative plan. See [ainative.studio/pricing](https://ainative.studio/pricing) for plan details.

---

## Privacy

### What is stored

Only facts, decisions, and observations extracted from the conversation — not the conversation itself.

Stored memories look like:
- `"Architecture: API gateway (Kong) cannot resolve Railway internal hostnames"`
- `"Convention: Use zerodb-local for unit tests — never hit production DB"`

### What is never stored

The plugin will never store:
- API keys, tokens, passwords, or any credentials
- Raw file contents or code snippets
- Personally identifiable information (emails, names, phone numbers) unless you explicitly `/remember` them
- Anything you mark with `[private]` in your message

### Data location

All memories are stored in your ZeroDB account on AINative's infrastructure. Memories are scoped to your user account and project — they are not shared with other users or used for training.

### Clearing your data

To wipe all memories for the current project:

```shell
/memory clear
```

This requires confirmation and is irreversible. To delete your entire ZeroDB account and all associated data, visit your [account settings](https://ainative.studio/dashboard/settings).

---

## Troubleshooting

### MCP server not connecting

**Symptom:** No `[ZeroDB Memory]` message at session start. `/recall` returns "MCP server unavailable."

**Fixes:**
1. Confirm `ZERODB_API_KEY` is set: `echo $ZERODB_API_KEY`
2. Test the MCP server directly: `npx ainative-zerodb-memory-mcp@latest --help`
3. Check if `~/.claude/settings.json` has the `zerodb-memory` MCP server configured (the plugin should have added it automatically on install — if missing, reinstall the plugin)
4. Verify your API key is valid at [ainative.studio/dashboard](https://ainative.studio/dashboard)

### No memories recalled at session start

**Symptom:** Session starts with `[ZeroDB Memory] 0 memories for this project`.

If this is your **first session**, that's expected — auto-persist hasn't stored anything yet. End the session with some real work and memories will be stored.

If you've used the plugin before, check:
- `ZERODB_AUTORECALL` is set to `on` (default)
- You're in the correct git repo directory — memory is scoped to your git remote
- Run `/memory list` to confirm memories exist for this project

### Auto-persist not firing

**Symptom:** Sessions end but `/memory stats` shows no new memories.

1. Check `ZERODB_AUTOPERSIST` is `on` (not `off` or `review`)
2. In `review` mode, Claude presents the memories and waits for your approval — check if there's a pending confirmation prompt
3. Auto-persist only fires if Claude used tools during the session (sessions with no tool use have nothing to extract)

### Out of credits

**Symptom:** Memory operations fail with a `402 Payment Required` or "insufficient credits" error.

Purchase additional credits at [ainative.studio/pricing](https://ainative.studio/pricing), or upgrade to a paid plan. Your existing memories are retained — only new store/recall operations are paused.

---

## Next Steps

- [ZeroDB Overview](/docs/zerodb/overview) — the full vector + graph database powering the plugin
- [ZeroMemory API](/docs/zeromemory/overview) — build your own memory-powered agents with the same API
- [MCP Servers](/docs/mcp/overview) — use ZeroDB's 76-tool MCP server for full database access from Claude Code
- [ainative.studio/signup](https://ainative.studio/signup?ref=claude-plugin) — get 500 free credits and start your first session