Guide · Agent skill
How to use the Session memory and improve() agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide covers the cognee-improve-sessions agent skill, which teaches an AI agent how cognee stores short-term session memory and how improve() later moves that content into a permanent knowledge graph. After reading it you will know how to install the skill, ask for session-aware memory in plain language, and interpret an improve() result, including why a stage was skipped or locked.
Session memory and improve()topoteretes/cognee · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it. It contains SKILL.md.
- 2Place the skill folder. Put it in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project only.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 4Install cognee and enable caching. Install the cognee Python library and keep CACHING=true, the default, so session memory works.
- 5Write to a session. Ask the agent to store a note or turn with a session_id, for example chat_1.
- 6Run improve() and read the result. Call improve() with dataset and session_ids, then check result.status and result.stage_summary() for any skipped or locked stages.
What the skill makes the agent do
cognee has two kinds of memory. Session memory is a fast cache of conversation turns, agent traces and feedback, keyed by session_id, and writing to it is instant with no LLM extraction. The permanent graph is what remember() builds without a session.
With this skill installed, the agent knows how to write and read session memory, choose the right remember() and recall() calls, run improve() in the correct order, and explain the nine-stage ImproveResult.
- Stores facts, Q&A turns, agent steps and feedback in a session
- Reads a session back and runs session-aware recall
- Runs improve() to bridge session content into the graph
- Explains skipped, already_completed and lock_held results
Install the skill (ZIP download or Claude apps)
Download the ZIP of the skill from this page. The skill is a single file, SKILL.md.
Option A: unzip it into ~/.claude/skills/ to make it available to your user account, or into a project's .claude/skills/ folder to make it available only in that project.
Option B: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
Trigger it with natural requests
You do not need to name the skill. The skill describes itself as useful when working with cognee's session memory or improve(), so requests that involve session_id, conversation turns, agent traces, feedback, bridging sessions into the graph, reading an ImproveResult, or tuning IMPROVE_* settings should bring it in.
Be specific about the session and the goal. Mention the session_id you are using and whether you want to write, read, or run improve().
- Save this preference to session chat_1 so the next answer can use it.
- Why did my improve() run report lock_held for this dataset?
- Bridge session support_42 into the main_dataset graph and show me the stage summary.
- Which IMPROVE_* setting should I change if stage 6 is always skipped?
Session write and improve() example
The skill uses calls like these. A session write returns immediately, and improve() bridges it in the background. Call wait_for_background_tasks() before a script exits so background work finishes.
import cognee
# Session write: returns immediately; improve() bridges it in the background
await cognee.remember("User prefers dark mode.", session_id="chat_1")
# Session-aware query: session cache first, then the graph
results = await cognee.recall("What does the user prefer?", session_id="chat_1")
# Bridge sessions into a dataset's graph explicitly
result = await cognee.improve(dataset="main_dataset", session_ids=["chat_1"])
print(result.status, result.stage_summary())
await cognee.wait_for_background_tasks() # before a script exitsReading the improve() result and skip reasons
improve() returns an ImproveResult. Its status is completed, errored, skipped, or running. Each of the nine stages reports a StageResult with a status of completed, already_completed, skipped, or errored, plus a reason. Stage 2, persist_session_qa, is the only fatal stage: if it fails, the rest do not run.
lock_held means another improve for the same dataset or session is already running. already_completed with a reason such as no_new_entries means nothing new has arrived since the last run.
- no_session_ids: a session stage ran without session_ids; pass them
- opt_in_disabled: pass build_truth_subspace=True, review_conflicts=True or build_global_context_index=True
- personalization_disabled: set PERSONALIZATION_ENABLED=true
- no_llm_configured: stages 4, 5, 8 and 9 need an LLM
- budget_exhausted: the LLM budget ran out (a 402); top up, then run improve again
What it needs and safety notes
You need the cognee Python library. Sessions require CACHING=true, which is the default. The cache backend is set by CACHE_BACKEND and can be sqlite (default), postgres, redis, fs or tapes. Sessions expire after SESSION_TTL_SECONDS, which defaults to 7 days.
The skill itself runs no scripts and makes no network calls. It documents the cognee API and its configuration. Stages that draft text (4, 5, 8 and 9) use an LLM provider, so if you configure one, those stages send data to it.
- Runs scripts: no
- Uses network: no (the cognee stages that call an LLM do, once you configure a provider)
- Optional LLM provider for stages 4, 5, 8 and 9
What people use it for
- Keeping a chatbot's per-conversation preferences in session memory and recalling them in the next turn
- Recording agent traces and step outcomes so later runs can learn from them
- Scoping recall to one project by pinning a session to a node_set
- Debugging why an improve() run reported lock_held or skipped stage 6
- Tuning IMPROVE_* settings for a team's cognee deployment
Frequently asked questions
How do I install the cognee-improve-sessions agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
Is the cognee-improve-sessions skill free and what is its licence?
The cognee project is released under the Apache-2.0 licence. The skill documents the cognee API, and this listing does not state any price for it.
What do I need to use this skill?
You need the cognee Python library. Session memory requires CACHING=true, which is the default, and a cache backend set by CACHE_BACKEND: sqlite (default), postgres, redis, fs or tapes. An LLM provider is optional and only needed for stages that draft text.
What does lock_held mean in improve()?
lock_held means another improve() run for the same dataset or session is already running, so this stage did not start. Wait for the other run to finish, then run improve() again.
Why was a stage skipped in my improve() run?
Each skipped stage has a reason. For example, no_session_ids means no session_ids were passed, and no_llm_configured means stages 4, 5, 8 and 9 have no LLM to draft text. The result's stage list shows the reason for each stage.
Does the skill run scripts or use the network?
No. The skill runs no scripts and uses no network. It only documents how the agent should call cognee. Stages that draft text will call your LLM provider if you configure one.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building an agent or chatbot on cognee and need session-aware memory, or if you are debugging improve() runs and IMPROVE_* settings. It covers only sessions and improve(), so if you only need general cognee setup or basic add and cognify usage, pick a resource that covers that instead.
Download the skill