How to use the cognee-performance agent skill for faster, cheaper runs

What the skill makes the agent do

The skill starts from one point in its source: the LLM is the bottleneck. Building the graph costs two LLM calls per chunk, one for graph extraction and one for summarization. Most tuning questions therefore come down to how many of those calls run, how fast, and on which model. Database and embedding work is small by comparison.

With the skill loaded, the agent can estimate cost with a dry run before ingesting, adjust ingestion knobs such as data_per_batch, chunks_per_batch and chunk_size, configure LLM and embedding rate limits, route individual stages to cheaper models, run work in the background, reduce read latency for chat-style use, and explain the single-process scaling limits of open-source cognee.

Install the skill from the ZIP or the Claude apps

Option one is a Claude Code style setup. Download the ZIP for this skill from our page and unzip it into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to limit it to that project. The skill's folder contains a single file, SKILL.md.

Option two is the Claude apps. Upload the ZIP under Settings, then Capabilities, then Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check that you have what the skill needs

The skill assumes an existing working setup. It is not a first-time guide for storing or searching documents with cognee. Before you use it, confirm the following.

• cognee is installed as a Python package
• An LLM provider API key or a local model endpoint is available for graph extraction and summarization
• Optional for production: Postgres with PGVector and Neo4j

Trigger the skill with natural requests

You do not need to name the skill. The skill description tells the agent when to use it: when cognee is slow, expensive, or hitting rate limits, or when you are planning how to scale a deployment. Describe the problem in your own words and the agent should pick it up.

Requests that fit the skill look like the examples below. Include the numbers you have, such as the document count, the error code or the model name, because the advice depends on them.

• Our cognee ingestion is slow on 2,000 PDFs. How can I speed it up without overloading the LLM?
• I keep getting 429 errors from my provider during remember() calls. What settings should I change?
• Estimate what it will cost to ingest this docs folder before I run it.
• Chat answers from cognee take too long. What can I turn off for read latency?
• We want to run a large import in the background. How do I track it?

Estimate cost and tune ingestion

Run a dry run before a large import. It returns per-stage token counts and an approximate cost, and makes no LLM calls. The estimate covers graph extraction and summarization only. It does not cover improve() or embeddings, so do not treat it as an exact figure. It is not available with GLiNER or a remote instance.

The main ingestion knobs are arguments to remember() and cognify(). data_per_batch (default 20) controls how many documents are processed at the same time. chunks_per_batch (default 2000, or the CHUNKS_PER_BATCH environment variable) controls how many chunks each extraction call receives. chunk_size defaults to the smaller of the embedding max tokens and half the LLM max tokens, about 8191 tokens with default OpenAI models. run_in_background returns immediately with status running, and self_improvement set to False skips the extra improve() step.

• Lower data_per_batch to reduce load; raise it for many small files
• Fewer, bigger chunks mean fewer LLM calls; smaller chunks give finer-grained graphs
• Worst-case concurrent LLM calls are about data_per_batch × min(chunks per document, chunks_per_batch) × 2

Handle rate limits and choose models per stage

Turn on LLM_RATE_LIMIT_ENABLED to cap requests per interval. The default is 60 requests per 60 seconds, and the default for local providers such as Ollama, llama.cpp and LM Studio is 10. AUTO_RATE_LIMIT is true by default: on a 429, 503, 529 or timeout it switches the limiter on for 15 minutes, extended while errors continue. Embedding calls retry rate-limit errors with exponential jitter, but AUTO_RATE_LIMIT does not apply to them, so enable EMBEDDING_RATE_LIMIT_ENABLED yourself for sustained load.

To use a cheaper or faster model for one stage, set the stage's variables: LLM_EXTRACTION_MODEL with its provider, endpoint, key and API version settings, plus LLM_SUMMARIZATION_* and LLM_QUERY_* for summaries and query answers. A stage routed to a local model does not inherit the local default of 10 requests, so set LLM_RATE_LIMIT_REQUESTS yourself.

• Structured-output calls retry with backoff for at least two attempts and four minutes
• Auth, not-found and quota errors are not retried
• LLM_ARGS passes extra litellm arguments to every call, such as a request timeout

Reduce read latency and plan scaling

For chat-style use, set AUTO_FEEDBACK to false. By default each answered turn makes one extra LLM call to analyze feedback. Keep CACHING set to true so session memory still works. When you only need passages rather than a generated answer, choose a search type that makes no LLM call, such as CHUNKS, CHUNKS_LEXICAL, SUMMARIES, CODE or SKILLS. Narrow searches with datasets and a smaller top_k.

For deployments, open-source cognee scales vertically in one process. The API server runs one worker, and its locks, caches and semaphores are in-process only, so extra workers or replicas against the same data are not coordinated. Horizontal, multi-server scaling is not covered by this skill. For production, the source recommends Postgres with PGVector and a graph-native backend such as Neo4j.

• AUTO_FEEDBACK=false is the biggest win for chat-style use
• Default embedded databases (SQLite, LanceDB, Ladybug) live on local disk
• distributed/deploy/ holds one-click deploy templates, not a distributed runner

Avoid the common pitfalls

Several settings look right but do nothing. Editing CHUNK_SIZE, CHUNK_OVERLAP or CHUNK_STRATEGY in .env.template has no effect on ingestion; pass chunk_size= to remember() instead. LLM_RATE_LIMIT_TOKENS and EMBEDDING_RATE_LIMIT_TOKENS do nothing, because only request-count limits are enforced. FALLBACK_MODEL is used only when the main model rejects content on policy grounds, not when it is slow or rate-limited.

Passing data_per_batch=None crashes, so omit the argument to get the default. A background cognify() is not tracked by cognee.wait_for_background_tasks(), so await its pipeline status yourself.

• Use chunk_size= in remember(), not CHUNK_SIZE in the environment file
• Do not expect token-based rate limit variables to work
• Omit data_per_batch rather than passing None