Claude Code

Quick Start

Install the plugin

Run these commands inside Claude Code:

/plugin marketplace add hydra-db/hydradb-claude-code
/plugin install hydradb@hydradb
/reload-plugins

Get credentials

Create an API key from the HydraDB dashboard
Create or copy your database ID from the HydraDB dashboard

Set environment variables

macOS/Linux (bash)
macOS/Linux (zsh)
Windows (PowerShell)

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

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

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

To verify the values are set:

macOS/Linux
Windows (PowerShell)

echo $HYDRADB_API_KEY
echo $HYDRADB_DATABASE

echo $env:HYDRADB_API_KEY
echo $env:HYDRADB_DATABASE

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.

Choosing HYDRADB_COLLECTION:

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.

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 tenant ID (your database ID)
`subTenantId`	`HYDRADB_COLLECTION`	Sub-tenant (collection) scope, a workspace-level namespace within your tenant. Set to `""` for default

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

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

Suggested Modes

Use case	`captureMode`	`searchMode`	`ingestionMode`
Everyday use, cross-session continuity, or a shared team 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-id"
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
}

Source code

hydradb-claude-code

View the source on GitHub.

Get Started

Usage

Concepts

Plugins

For Agents

Quick Start

Commands

Modes

`captureMode`: how conversations are saved

`searchMode`: what is recalled at prompt time

`ingestionMode`: where workspace docs are synced

`recallMode`: speed vs. depth

Config Variables

Required

Core behavior

Limits

Timeouts

File filtering

Advanced

Config File Location Priority

Suggested Modes

Suggested Configs

Minimal (env vars only)

Recommended workspace config (`.hydradb-plugin.json`)

Maximum recall

Manual-save only (no auto-capture)

Source code

hydradb-claude-code

​Quick Start

​Commands

​Modes

​captureMode: how conversations are saved

​searchMode: what is recalled at prompt time

​ingestionMode: where workspace docs are synced

​recallMode: speed vs. depth

​Config Variables

​Required

​Core behavior

​Limits

​Timeouts

​File filtering

​Advanced

​Config File Location Priority

​Suggested Modes

​Suggested Configs

​Minimal (env vars only)

​Recommended workspace config (.hydradb-plugin.json)

​Maximum recall

​Manual-save only (no auto-capture)

​Source code

hydradb-claude-code

Quick Start

Commands

Modes

`captureMode`: how conversations are saved

`searchMode`: what is recalled at prompt time

`ingestionMode`: where workspace docs are synced

`recallMode`: speed vs. depth

Config Variables

Required

Core behavior

Limits

Timeouts

File filtering

Advanced

Config File Location Priority

Suggested Modes

Suggested Configs

Minimal (env vars only)

Recommended workspace config (`.hydradb-plugin.json`)

Maximum recall

Manual-save only (no auto-capture)

Source code