> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Cognee

> Trace Cognee semantic memory workflows with Respan — auto-instrumented spans and full observability.

[Cognee](https://www.cognee.ai/) is an open-source memory engine with a semantic graph at its core that provides observability for AI agents and semantic workflows. The Cognee–Respan integration patches Cognee's `@observe` decorator so every task and workflow run becomes a Respan span automatically.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Resources

* [Cognee Respan integration docs](https://docs.cognee.ai/integrations/respan-integration)
* [Cognee blog: Observability for semantic workflows](https://www.cognee.ai/blog/deep-dives/observability-for-semantic-workflows)

#### Tracing

## Setup

#### Install packages

```bash
pip install respan-ai cognee-community-observability-respan
```

#### Set environment variables

```bash
export MONITORING_TOOL="respan"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export LLM_API_KEY="YOUR_OPENAI_API_KEY"
```

`MONITORING_TOOL=respan` tells Cognee to use Respan as its observability backend. `LLM_API_KEY` is required if your pipeline calls LLMs.

#### Initialize and run

```python
import asyncio
import cognee_community_observability_respan  # noqa: F401 — patches Cognee on import
from cognee.modules.observability.get_observe import get_observe

observe = get_observe()  # returns Respan-backed decorator

@observe
def process_documents(documents: list[str]):
    return [f"Processed: {doc}" for doc in documents]

@observe
def create_knowledge_graph(processed_docs: list[str]):
    return [{"id": i, "content": doc} for i, doc in enumerate(processed_docs)]

@observe(workflow=True)
async def semantic_workflow():
    documents = ["Document 1", "Document 2", "Document 3"]
    processed = process_documents(documents)
    return create_knowledge_graph(processed)

result = asyncio.run(semantic_workflow())
print(f"Created knowledge graph with {len(result)} nodes")
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your Cognee workflow with task spans, knowledge graph operations, and LLM calls.

## How it works

The Respan integration patches Cognee's `get_observe()` at import time so:

* `@observe` maps to Respan's `task()` decorator.
* `@observe(workflow=True)` maps to Respan's `workflow()` decorator.
* Telemetry is initialized once via `RespanTelemetry()` on import.

## Configuration

| Variable          | Description               | Required |
| ----------------- | ------------------------- | -------- |
| `MONITORING_TOOL` | Set to `respan`           | Yes      |
| `RESPAN_API_KEY`  | Your Respan API key       | Yes      |
| `LLM_API_KEY`     | Your LLM provider API key | Optional |

## Custom span names

```python
@observe(name="custom_task_name")
def my_task():
    pass

@observe(workflow=True, name="custom_workflow_name")
async def my_workflow():
    pass
```

## Troubleshooting

| Issue                 | Solution                                                                           |
| --------------------- | ---------------------------------------------------------------------------------- |
| No traces             | Ensure `RESPAN_API_KEY` is set and `MONITORING_TOOL=respan`.                       |
| Decorators don't fire | Import `cognee_community_observability_respan` **before** calling `get_observe()`. |