> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> HydraDB plugin for Claude Code: persistent memory across sessions and projects.

## Quick Start

<Steps>
  <Step title="Install the plugin">
    Run these commands inside Claude Code:

    ```bash theme={"dark"}
    /plugin marketplace add hydra-db/hydradb-claude-code
    /plugin install hydradb@hydradb
    /reload-plugins
    ```
  </Step>

  <Step title="Get credentials">
    * Create an API key from the [HydraDB dashboard](https://app.hydradb.com/keys)
    * Create or copy your database ID from the [HydraDB dashboard](https://app.hydradb.com/databases)
  </Step>

  <Step title="Set environment variables">
    <Tabs>
      <Tab title="macOS/Linux (bash)">
        ```bash theme={"dark"}
        echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.bashrc
        echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.bashrc
        echo 'export HYDRADB_COLLECTION=""' >> ~/.bashrc
        source ~/.bashrc
        ```
      </Tab>

      <Tab title="macOS/Linux (zsh)">
        ```bash theme={"dark"}
        echo 'export HYDRADB_API_KEY="your-api-key"' >> ~/.zshrc
        echo 'export HYDRADB_DATABASE="your-database-id"' >> ~/.zshrc
        echo 'export HYDRADB_COLLECTION=""' >> ~/.zshrc
        source ~/.zshrc
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={"dark"}
        [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")
        ```
      </Tab>
    </Tabs>

    To verify the values are set:

    <Tabs>
      <Tab title="macOS/Linux">
        ```bash theme={"dark"}
        echo $HYDRADB_API_KEY
        echo $HYDRADB_DATABASE
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={"dark"}
        echo $env:HYDRADB_API_KEY
        echo $env:HYDRADB_DATABASE
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run setup and verify">
    ```bash theme={"dark"}
    /hydradb:setup
    /hydradb:status
    ```
  </Step>
</Steps>

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

**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](/essentials/memories) only |
| `knowledge` | Recalls from [Knowledge](/essentials/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](/essentials/memories) using `infer` |
| `knowledge` | Syncs workspace docs into the [Knowledge](/essentials/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 |

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

***

## 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](#modes)) |
| `searchMode` | `memory` | What to recall at prompt time (see [Modes](#modes)) |
| `ingestionMode` | `memory` | Where workspace docs are synced (see [Modes](#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 |

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

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

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

```bash theme={"dark"}
export HYDRADB_API_KEY="your-api-key"
export HYDRADB_DATABASE="your-database-id"
export HYDRADB_COLLECTION=""
```

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

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{
  "captureMode": "both",
  "searchMode": "both",
  "ingestionMode": "auto",
  "maxContextChars": 10000,
  "maxMemoryResults": 8,
  "maxKnowledgeResults": 6
}
```

### Manual-save only (no auto-capture)

```json theme={"dark"}
{
  "captureMode": "off",
  "autoRecall": true,
  "autoIngest": true
}
```

***

## Source code

<Card title="hydradb-claude-code" icon="github" href="https://github.com/hydra-db/hydradb-claude-code">
  View the source on GitHub.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.