Claude Code

Give Claude Code long-term memory with the HydraDB plugin: recall before each prompt, workspace doc sync, and saved conversations.

The HydraDB plugin for Claude Code recalls relevant notes when you send a prompt, syncs your workspace docs into HydraDB, and saves conversations as durable memories. The plugins for Codex, Cursor, OpenCode, Muse Code, Grok Build, and OpenClaw run on the same engine, so the modes and config variables on this page apply to them too.

Quick Start

1. Install the plugin

   Run these commands inside Claude Code:

   /plugin marketplace add hydra-db/hydradb-claude-code
   /plugin install hydradb@hydradb
   /reload-plugins
   
2. Get credentials

   • Create an API key from the HydraDB dashboard
   • Create or copy your database ID from the HydraDB dashboard
3. Set environment variables

   macOS/Linux (bash)

   echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.bashrc
   echo 'export HYDRADB_DATABASE="your-database"' >> ~/.bashrc
   echo 'export HYDRADB_COLLECTION=""' >> ~/.bashrc
   source ~/.bashrc
   

   macOS/Linux (zsh)

   echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.zshrc
   echo 'export HYDRADB_DATABASE="your-database"' >> ~/.zshrc
   echo 'export HYDRADB_COLLECTION=""' >> ~/.zshrc
   source ~/.zshrc
   

   Windows (PowerShell)

   [System.Environment]::SetEnvironmentVariable("HYDRADB_API_KEY", "your-api-key", "User")
   [System.Environment]::SetEnvironmentVariable("HYDRADB_DATABASE", "your-database", "User")
   [System.Environment]::SetEnvironmentVariable("HYDRADB_COLLECTION", "", "User")
   

   To verify the values are set:

   macOS/Linux

   echo $HYDRADB_API_KEY
   echo $HYDRADB_DATABASE
   

   Windows (PowerShell)

   echo $env:HYDRADB_API_KEY
   echo $env:HYDRADB_DATABASE
   
4. Run setup and verify

   /hydradb:setup
   /hydradb:status
   

HYDRADB_COLLECTION must be set explicitly. To use the default collection, set it to an empty string ("") rather than omitting it. These names need plugin 1.1.0 or later. The older names HYDRA_DB_API_KEY, HYDRADB_TENANT_ID, and HYDRADB_SUB_TENANT_ID still work, but print a deprecation warning.

HYDRADB_COLLECTION strategy:

• Use a workspace-specific value (e.g., claude-my-project) for project-isolated memory.
• Use a shared value to carry memory across all sessions and workspaces.

Once configured, the plugin runs in the background: it syncs workspace docs on session start, recalls relevant context before each prompt, and captures conversation memory after each response.

Repo: hydradb-claude-code.

---

Commands

Command	Description
/hydradb:setup	Interactive configuration wizard
/hydradb:status	Show current config and connection status
/hydradb:search <query>	Search HydraDB manually
/hydradb:remember <note>	Save a note to memory
/hydradb:save-session	Manually save the full session to HydraDB
/hydradb:sync-workspace [--force]	Force re-sync workspace docs

Modes

captureMode: how conversations are saved

Value	Behavior
session-upsert	(default) Maintains one evolving session transcript, upserted after each response
turn	Saves each user/assistant exchange as an isolated memory
both	Saves isolated turns and a rolling session transcript
off	No automatic saves; manual saves still work via /hydradb:save-session

searchMode: what is recalled at prompt time

Value	Behavior
memory	(default) Recalls from Memories only
knowledge	Recalls from Knowledge only
both	Recalls from both in parallel, then merges results

ingestionMode: where workspace docs are synced

Value	Behavior
memory	(default) Syncs workspace docs into Memories using infer
knowledge	Syncs workspace docs into the Knowledge base
auto	Prefers memory; falls back to knowledge for larger files. Pair with searchMode: "both"

recallMode: speed vs. depth

Value	Behavior
fast	(default) Lower latency, standard recall
thinking	Deeper reasoning-based recall via graph traversal

By default, HydraDB syncs each conversation pair (user and assistant) that does not include the ignoreMarker (hydra-ignore). For manual-only capture, set captureMode to off and use /hydradb:save-session or /hydradb:remember <text>.

Config Variables

Required

Variable	Env var	Description
apiKey	HYDRADB_API_KEY	Your HydraDB API key
tenantId	HYDRADB_DATABASE	Your HydraDB database
subTenantId	HYDRADB_COLLECTION	Collection scope. Set to "" for the default collection

Core behavior

Variable	Default	Description
autoRecall	true	Inject HydraDB context before every prompt automatically
autoIngest	true	Sync workspace docs on session start and file edits automatically
captureMode	session-upsert	How conversations are saved (see Modes)
searchMode	memory	What to recall at prompt time (see Modes)
ingestionMode	memory	Where workspace docs are synced (see Modes)
recallMode	fast	Recall depth: fast or thinking
graphContext	true	Include entity paths and graph relations in recalled context

Limits

Variable	Default	Description
maxContextChars	7000	Max characters injected into the prompt from HydraDB
maxMemoryResults	6	Max memory chunks returned per recall
maxKnowledgeResults	4	Max knowledge chunks returned per recall
maxFileSizeBytes	52428800 (50 MB)	Max file size for workspace sync
maxFilesPerSync	25	Max files synced per pass
maxMemoryCharsPerChunk	52428800 (50 MB)	Max chars per memory chunk
maxMemoryChunksPerFile	1	Max chunks per file

Timeouts

Variable	Env var	Default	Description
requestTimeoutMs	HYDRADB_REQUEST_TIMEOUT_MS	15000	Timeout for recall/read requests (ms)
writeTimeoutMs	HYDRADB_WRITE_TIMEOUT_MS	15000	Timeout for sync/write requests (ms)

File filtering

Variable	Default	Description
includeGlobs	CLAUDE.md, .claude/**/*.md, **/*.md, **/*.mdx	Files included in workspace sync
excludeGlobs	.git/**, node_modules/**, dist/**, **/.env*, **/*.key, etc.	Files excluded from workspace sync
ignoreMarker	hydra-ignore	Add to a file or prompt to skip capture and sync

By default, HydraDB includes .md and .mdx files in workspace sync. To include additional file types, extend includeGlobs in your config file.

Advanced

Variable	Default	Description
subTenantId	-	Collection: a workspace-level namespace within your database
userName	-	Optional user name attached to memories
apiBaseUrl	https://api.hydradb.com	HydraDB API base URL
memoryCustomInstructions	-	Custom instructions for how conversation memories are extracted
workspaceMemoryCustomInstructions	-	Custom instructions for how workspace doc memories are extracted
debug	false	Enable debug logging to .hydradb-plugin-data/debug.log

Config File Location Priority

The plugin resolves config in this order (later sources override earlier ones):

1. Built-in defaults
2. HYDRADB_PLUGIN_CONFIG env var (absolute path to a JSON file)
3. ${CLAUDE_PLUGIN_DATA}/config.json
4. .hydradb-plugin-data/config.json
5. .hydradb-plugin.json (workspace-shared, safe to commit to git)
6. .hydradb-plugin.local.json (workspace-local, add to .gitignore)
7. Environment variable overrides

Suggested Modes

Use case	captureMode	searchMode	ingestionMode
Default / everyday use	session-upsert	memory	memory
Cross-session continuity	session-upsert	memory	memory
Team shared knowledge base	session-upsert	memory	memory
Maximum recall coverage	both	both	auto
Recall only, no auto-save	off	memory	memory
Isolated turn snapshots	turn	memory	memory

Suggested Configs

Minimal (env vars only)

export HYDRADB_API_KEY="your-api-key"
export HYDRADB_DATABASE="your-database"
export HYDRADB_COLLECTION=""

Recommended workspace config (.hydradb-plugin.json)

{
  "apiKey": "${HYDRADB_API_KEY}",
  "tenantId": "${HYDRADB_DATABASE}",
  "subTenantId": "claude-my-workspace",
  "autoRecall": true,
  "autoIngest": true,
  "captureMode": "session-upsert",
  "searchMode": "memory",
  "ingestionMode": "memory",
  "recallMode": "fast",
  "graphContext": true,
  "maxContextChars": 7000,
  "requestTimeoutMs": 15000,
  "writeTimeoutMs": 15000
}

Maximum recall

{
  "captureMode": "both",
  "searchMode": "both",
  "ingestionMode": "auto",
  "maxContextChars": 10000,
  "maxMemoryResults": 8,
  "maxKnowledgeResults": 6
}

Manual-save only (no auto-capture)

{
  "captureMode": "off",
  "autoRecall": true,
  "autoIngest": true
}