Claude Code

Quick Start

Install the plugin

Run these commands inside Claude Code:

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

Get credentials

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

Set environment variables

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

echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.bashrc
echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.bashrc
echo 'export HYDRADB_SUB_TENANT_ID=""' >> ~/.bashrc
source ~/.bashrc

echo 'export HYDRA_DB_API_KEY="your-api-key"' >> ~/.zshrc
echo 'export HYDRADB_TENANT_ID="your-tenant-id"' >> ~/.zshrc
echo 'export HYDRADB_SUB_TENANT_ID=""' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable("HYDRA_DB_API_KEY", "your-api-key", "User")
[System.Environment]::SetEnvironmentVariable("HYDRADB_TENANT_ID", "your-tenant-id", "User")
[System.Environment]::SetEnvironmentVariable("HYDRADB_SUB_TENANT_ID", "", "User")

To verify the values are set:

macOS/Linux
Windows (PowerShell)

echo $HYDRA_DB_API_KEY
echo $HYDRADB_TENANT_ID

echo $env:HYDRA_DB_API_KEY
echo $env:HYDRADB_TENANT_ID

Run setup and verify

/hydradb:setup
/hydradb:status

HYDRADB_SUB_TENANT_ID must be set explicitly. If you want the plugin to use its default sub-tenant, set it to an empty string ("") rather than omitting it entirely.

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

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`	`HYDRA_DB_API_KEY`	Your HydraDB API key
`tenantId`	`HYDRADB_TENANT_ID`	Your HydraDB tenant ID
`subTenantId`	`HYDRADB_SUB_TENANT_ID`	Sub-tenant scope. 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
`subTenantId`	-	Workspace-level namespace within your tenant
`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`
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 HYDRA_DB_API_KEY="your-api-key"
export HYDRADB_TENANT_ID="your-tenant-id"
export HYDRADB_SUB_TENANT_ID=""

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

{
  "apiKey": "${HYDRA_DB_API_KEY}",
  "tenantId": "${HYDRADB_TENANT_ID}",
  "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 & Show Support

If this HydraDB plugin makes your Claude Code workflow faster (and smarter), please star the open-source repo that powers it.

hydradb-claude-code

Star on GitHub if you found it useful.

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 & Show Support

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 & Show Support

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 & Show Support