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

# Vellum

> Add persistent memory to Vellum agents with Cognee.

Connect Vellum agents to Cognee so prompts, tool calls, and responses are captured automatically and persisted as memory.

## Why Use This Integration

* **Zero-code memory**: the plugin captures prompts, tool traces, and responses automatically
* **Cross-session memory**: context persists across agent instances and conversation sessions
* **Flexible backend**: use a plugin-managed local Cognee server, your own self-hosted server, or Cognee Cloud

## Prerequisites

* A Vellum account and the Vellum CLI
* A Cognee API key if you are using Cognee Cloud
* An LLM API key if you are using local Cognee and want graph sync to work
* An agent already hatched in Vellum

<Note>
  Vellum plugins are configured per agent, so you need to hatch the agent before installing Cognee.
</Note>

## Quick Start

Use the local flow if you want Cognee to run with a managed local server. Use the cloud flow if you want to connect Vellum to Cognee Cloud. You can also install the plugin from the Vellum web app instead of the CLI: open your assistant, go to the **Plugins** tab, search for **Cognee**, and install it there — the credentials shown below still need to be configured.

<Info>
  The examples below use `my-assistant` as the agent name. Use the same name in every command.
</Info>

<Note>
  **Two separate API keys are involved.** The Vellum provider key (set with `vellum setup`) is what the agent itself uses to chat — hatch configures Anthropic as the default provider. The Cognee `llm_api_key` credential is used by the Cognee server to build the knowledge graph during sync. Cognee does not reuse the Vellum provider key, so configure both — they can hold the same value if both use the same LLM provider.
</Note>

<Tabs>
  <Tab title="Local">
    Set up a local agent, configure both keys, and install the plugin:

    ```bash theme={null}
    vellum hatch --name my-assistant --remote docker
    vellum setup --provider anthropic
    vellum exec my-assistant -- assistant credentials set sk-... --service cognee --field llm_api_key
    vellum exec my-assistant -- assistant plugins install cognee
    ```

    After setup, you can talk to the agent as usual, for example with:

    ```bash theme={null}
    vellum client my-assistant
    ```

    <Note>
      If the agent replies with `provider_connection "anthropic-personal" has no API key stored`, the Vellum provider key is missing — run `vellum setup --provider anthropic`, or store one directly with `vellum exec my-assistant -- assistant keys set anthropic sk-ant-...`. See the [Vellum docs](https://www.vellum.ai/docs) for advanced agent setup options.
    </Note>
  </Tab>

  <Tab title="Cognee Cloud">
    Set the Cognee Cloud credentials for the agent and install the plugin:

    ```bash theme={null}
    vellum hatch --name my-assistant --remote docker
    vellum setup --provider anthropic
    vellum exec my-assistant -- assistant credentials set your-cognee-api-key --service cognee --field api_key
    vellum exec my-assistant -- assistant credentials set https://your-cognee-server-url --service cognee --field base_url
    vellum exec my-assistant -- assistant plugins install cognee
    ```

    The Cognee Cloud backend provides its own provider configuration, so you do not need to set an LLM API key for graph sync in this mode. The Vellum provider key is still required for the agent to chat.
  </Tab>
</Tabs>

## How It Works

The plugin hooks into the Vellum agent lifecycle to capture and recall memory automatically:

| Hook                 | Fires                    | What it does                                                                                                                                |
| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `init`               | Plugin load              | Disables Vellum's default memory so Cognee is the sole memory provider, resolves the Cognee backend, and mints an API key for local servers |
| `user-prompt-submit` | Each user turn           | Recalls relevant context from Cognee and injects it into the conversation                                                                   |
| `post-tool-use`      | After each tool call     | Stores the tool call as a trace entry in session memory                                                                                     |
| `stop`               | Turn end                 | Pairs the user prompt with the assistant response as a QA entry and triggers graph sync when the threshold is reached                       |
| `post-compact`       | After context compaction | Injects a memory anchor (recent QA pairs, traces, graph context) into the compacted history                                                 |
| `shutdown`           | Plugin unload            | Runs a final graph sync and unregisters the agent connection                                                                                |

See the [hook mapping in the integration README](https://github.com/topoteretes/cognee-integrations/tree/main/integrations/vellum-assistant#hook-mapping) for implementation details.

## Update or Remove

Upgrade the plugin to the current marketplace pin:

```bash theme={null}
vellum exec my-assistant -- assistant plugins upgrade cognee
```

Remove it from the agent:

```bash theme={null}
vellum exec my-assistant -- assistant plugins uninstall cognee
```

***

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/topoteretes/cognee-integrations/tree/main/integrations/vellum-assistant">
    View the Vellum integration source code
  </Card>

  <Card title="Vellum GitHub" icon="github" href="https://github.com/vellum-ai/vellum-assistant">
    Learn more about the Vellum assistant project
  </Card>
</CardGroup>