Skip to main content

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.

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"
  • "Meta LLAMA API is region-blocked intermittently, fall back to HuggingFace"

Installation​

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

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 — 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​

echo 'export ZERODB_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
Never commit your API key

Add .env to your .gitignore. Use shell profile exports or a secrets manager for production environments.

3. Verify​

# 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: Meta LLAMA API is region-blocked intermittently, fallback to HuggingFace
• In-Progress: Billing sprint — 3 paying customers, fixing invoice generation
• Correction: Don't use alembic upgrade head in production, use sync-production-schema.py
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:

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

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

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

/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:

SubcommandWhat it does
/memory listPaginated list of all memories for the current project
/memory statsCount, storage used, credits consumed, last sync time
/memory exportExport memories as JSON (default) or Markdown
/memory export --format claudemdGenerate a CLAUDE.md from your memories
/memory autopersist on|off|reviewControl auto-persist behavior
/memory autorecall on|offEnable or disable auto-recall at session start
/memory clearWipe all memories for the current project (requires confirmation)

Examples​

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

VariableDefaultDescription
ZERODB_API_KEY—Required. Your ZeroDB API key. Get one at ainative.studio/signup.
ZERODB_PROJECT_IDAuto-detectedZeroDB project ID. Auto-detected from your git remote URL. Override if you want to point multiple repos at the same memory namespace.
ZERODB_AUTOPERSISTonAuto-persist mode. on = save automatically, off = never auto-save, review = show memories before saving.
ZERODB_AUTORECALLonAuto-recall at session start. on = inject memories automatically, off = manual /recall only.
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:

/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​

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

OperationCredits
Store memory1 credit
Semantic search (/recall)2 credits
Get context bundle (auto-recall)3 credits
Embed text1 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 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:

/memory clear

This requires confirmation and is irreversible. To delete your entire ZeroDB account and all associated data, visit your account 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

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, or upgrade to a paid plan. Your existing memories are retained — only new store/recall operations are paused.

Next Steps​

  • ZeroDB Overview — the full vector + graph database powering the plugin
  • ZeroMemory API — build your own memory-powered agents with the same API
  • MCP Servers — use ZeroDB's 76-tool MCP server for full database access from Claude Code
  • ainative.studio/signup — get 500 free credits and start your first session