> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> HydraDB plugin for Claude Code. Persistent memory and contextual awareness across sessions and projects.

## Quick Start

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

    ```bash theme={"dark"}
    /plugin marketplace add usecortex/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 tenant ID from the [HydraDB dashboard](https://app.hydradb.com/tenants)
  </Step>

  <Step title="Set environment variables">
    <Tabs>
      <Tab title="macOS/Linux (bash)">
        ```bash theme={"dark"}
        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
        ```
      </Tab>

      <Tab title="macOS/Linux (zsh)">
        ```bash theme={"dark"}
        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
        ```
      </Tab>

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

    To verify the values are set:

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

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

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

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

**`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](/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`      | `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](#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                                                      |
| ----------------------------------- | ------------------------- | ---------------------------------------------------------------- |
| `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):

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)

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

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

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

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

  <Card title="hydradb-claude-code" icon="star" href="https://github.com/usecortex/hydradb-claude-code">
    Star on GitHub if you found it useful.
  </Card>
</Note>