hydradb

HydraDB Claude Code Plugin

Secure HydraDB automation for Claude Code with markdown-first workspace sync, prompt-time recall, and configurable memory capture modes.

The plugin gives Claude Code persistent, cross-session memory powered by HydraDB. It hooks into the Claude Code lifecycle to automatically recall relevant context at prompt time, sync workspace documentation into HydraDB, and capture conversation content as durable memories.

Features

• Automatic recall — injects relevant memories and knowledge into Claude's context on every prompt
• Workspace sync — syncs markdown-first documentation (*.md, *.mdx, CLAUDE.md) into HydraDB
• Session capture — saves conversation content as evolving session memories or isolated turn memories
• Graph context — surfaces entity path chains and chunk-level relations from HydraDB's knowledge graph
• Secret redaction — heuristic filtering strips common secret patterns before any data leaves the workspace
• Configurable modes — fine-grained control over capture, search, and ingestion behavior

Prerequisites

• Node.js >= 18
• npm
• A HydraDB account with an API key and tenant ID — sign up at hydradb.com
• Claude Code installed

Quick Start

git clone https://github.com/usecortex/hydradb-claude-code.git
cd hydradb-claude-code
make bootstrap

The bootstrap script will:

1. Verify Node.js >= 18 and npm are installed
2. Run npm install
3. Create config.json from config.example.json (if it doesn't already exist)
4. Run a syntax check
5. Print next steps

Then set your credentials:

export HYDRADB_API_KEY="your-api-key"
export HYDRADB_TENANT_ID="your-tenant-id"

Install the plugin in Claude Code:

/plugin marketplace add /path/to/hydradb-claude-code
/plugin install hydradb@hydradb

Or, once the repo is public:

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

Reload Claude Code and run /hydradb:status to verify.

Configuration

The plugin resolves configuration from multiple layers (later layers override earlier ones):

1. Built-in defaults
2. HYDRADB_PLUGIN_CONFIG environment variable
3. ${CLAUDE_PLUGIN_DATA}/config.json
4. ./.hydradb-plugin-data/config.json
5. .hydradb-plugin.json
6. .hydradb-plugin.local.json
7. Environment variable overrides

Minimal config

{
  "apiBaseUrl": "https://api.hydradb.com",
  "apiKey": "${HYDRADB_API_KEY}",
  "tenantId": "${HYDRADB_TENANT_ID}",
  "subTenantId": "",
  "autoRecall": true,
  "autoIngest": true,
  "captureMode": "session-upsert",
  "searchMode": "memory",
  "ingestionMode": "memory"
}

Config reference

Field	Default	Description
apiBaseUrl	https://api.hydradb.com	HydraDB API endpoint
apiKey	—	HydraDB API key (use ${HYDRADB_API_KEY} to reference env var)
tenantId	—	HydraDB tenant ID (use ${HYDRADB_TENANT_ID} to reference env var)
subTenantId	—	Sub-tenant scope; set to "" for HydraDB's default sub-tenant
userName	—	Display name attached to captured memories
autoRecall	true	Automatically recall HydraDB context on each user prompt
autoIngest	true	Automatically sync workspace docs on session start
captureMode	session-upsert	turn, session-upsert, both, or off
searchMode	memory	memory, knowledge, or both
ingestionMode	memory	memory, knowledge, or auto
recallMode	thinking	Recall strategy passed to HydraDB
graphContext	true	Include graph entity paths and relations in recall
maxContextChars	7000	Max characters injected into Claude's context per prompt
maxMemoryResults	6	Max memory chunks returned per recall
maxKnowledgeResults	4	Max knowledge chunks returned per recall
requestTimeoutMs	15000	Timeout for HydraDB read requests
writeTimeoutMs	15000	Timeout for HydraDB write requests
maxFileSizeBytes	52428800	Max file size for workspace sync (50 MB)
maxFilesPerSync	25	Max files synced per workspace sync run
includeGlobs	["CLAUDE.md", ".claude/**/*.md", "**/*.md", "**/*.mdx"]	File patterns to include in workspace sync
excludeGlobs	(see config.example.json)	File patterns to exclude from workspace sync
ignoreMarker	hydra-ignore	Marker string to skip capture/sync for specific files or prompts
memoryCustomInstructions	(see config.example.json)	Instructions for memory extraction from conversations
workspaceMemoryCustomInstructions	(see config.example.json)	Instructions for memory extraction from workspace docs
debug	false	Enable JSONL debug logging

Environment variable overrides