Agent skill

Cognee Session Memory and Improve

by topoteretes in topoteretes/cognee

Explains how cognee stores session memory by session_id and bridges it into the permanent graph with improve(), including the stages, results and settings.

Apache-2.0Auto-check passedAgent Workflows

Install Cognee Session Memory and Improve

skills CLI
$ npx skills add topoteretes/cognee --skill cognee-improve-sessions -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install topoteretes/cognee cognee-improve-sessions --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/topoteretes/cognee.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/cognee-improve-sessions .claude/skills/cognee-improve-sessions && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
cognee-improve-sessions
GitHub stars
32k
Token cost
~3.2k tokens
SKILL.md length
1,335 words
Files
1
Skills in repo
19
Repo updated
First seen
Licence
Apache-2.0

At a glance

Explains how cognee stores session memory by session_id and bridges it into the permanent graph with improve(), including the stages, results and settings.

  • Works in 5 steps: Subclass BaseStage in… → Insert it into DEFAULT_STAGES in… → If it can re-run cheaply, give it a… → …
  • Storing conversation turns or agent traces under a session_id in cognee
  • SKILL.md covers Use it, Pitfalls, How it works and Extending it
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

This reference separates cognee's two kinds of memory: a fast session cache of conversation turns, agent traces and feedback keyed by session_id, and the permanent graph that remember() builds without a session. It shows how to write each kind of entry, using remember() with text, a QAEntry, a TraceEntry or a FeedbackEntry, recall() with a completion search type, and cognee.session.get_session() to read a session back.

improve() connects the two, and remember() calls it automatically, so most users never call it directly. It runs nine ordered stages, each gated before it spends any LLM or embedding cost, and returns an ImproveResult with one StageResult per stage. The reference explains why a stage is skipped, already_completed or lock_held, and which stage is the only fatal one. Caching must be on, the backend can be sqlite, postgres, redis, fs or tapes, and sessions expire after seven days by default.

When your agent uses it

  • Storing conversation turns or agent traces under a session_id in cognee
  • Working out why an improve() stage was skipped or reported lock_held
  • Tuning the IMPROVE settings or the session cache backend and expiry

Example prompts

  • “Save these chat turns into a cognee session and bridge them into the graph with improve().”
  • “Why did my improve() run report already_completed for the persist stage?”
  • “Switch the cognee session cache from sqlite to redis and explain the expiry setting.”

Requirements

  • cognee installed in a Python project
  • Session caching enabled (the default)

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Subclass BaseStage in cognee/modules/improve/stages.py. Set name,
  2. Insert it into DEFAULT_STAGES in registry.py at the right position.
  3. If it can re-run cheaply, give it a watermark so a repeat run reports
  4. If it writes graph data under a new pipeline name, add that name to
  5. Tests: cognee/tests/unit/modules/improve/ (gates, results, config) and

What it can do on your machine

Read from SKILL.md and the folder at commit 0ec7a9f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are python).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Cognee Session Memory and Improve loads about 3.2k tokens when it runs. Until then it costs about 85 tokens; SKILL.md has 1,335 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~85
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from topoteretes/cognee at commit 0ec7a9f, republished under its Apache-2.0 licence (© topoteretes). 1,335 words, ~3,174 tokens.

Download SKILL.mdSave it as .claude/skills/cognee-improve-sessions/SKILL.md (or your agent's skills folder).
name
cognee-improve-sessions
description
Use when working with cognee's session memory or improve() — storing conversation turns, agent traces and feedback with session_id, bridging sessions into the permanent graph, reading an ImproveResult, understanding why an improve stage was skipped, already_completed or lock_held, or tuning the IMPROVE_* settings.

Session memory and improve()

cognee has two kinds of memory:

  • Session memory: a fast cache of conversation turns, agent traces, and feedback, keyed by session_id. Writing is instant, with no LLM extraction.
  • The permanent graph: what remember() builds without a session.

improve() connects them. It bridges session content into the graph and enriches the graph itself. remember() calls it automatically, so most users never call it directly.

python
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 exits

Use it

Writing session memory
WhatHow
A fact or noteremember(text, session_id=...) (stored as a Q&A entry with the text as the answer)
A Q&A turnrecall(query, session_id=...) with a completion search type saves the turn itself; or remember(cognee.QAEntry(question=..., answer=...), session_id=...)
An agent stepremember(cognee.TraceEntry(origin_function=..., status="success", ...), session_id=...), or the @cognee.agent_memory(save_session_traces=True) decorator
Feedback on an answerremember(cognee.FeedbackEntry(qa_id=..., feedback_score=...), session_id=...) or cognee.session.add_feedback(session_id, qa_id, feedback_text=..., feedback_score=...)
Read a sessioncognee.session.get_session(session_id, last_n=...)

Requirements: CACHING=true (default). The cache backend is CACHE_BACKEND, one of sqlite (default), postgres, redis, fs, tapes. Sessions expire after SESSION_TTL_SECONDS (default 7 days).

What improve() does: nine stages, in order

Every run goes through the same ordered stages (cognee/modules/improve/registry.py). Each stage checks a gate before it spends any LLM or embedding cost, and reports one StageResult.

#StageWhat it doesRuns when
1feedback_weightsAdjusts the weight of graph elements that rated answers usedsession_ids given; adapter supports feedback weights
2persist_session_qaTurns session Q&A into graph content (node set user_sessions_from_cache)session_ids given. The only fatal stage
3persist_agent_tracesTurns agent-trace feedback into graph contentsession_ids given
4extract_agent_contextDrafts agent-profile lessons from tracessession_ids, CACHING + AUTO_FEEDBACK, an LLM
5distill_sessionsDistills session learnings into the graphsession_ids, an LLM
6update_user_preferencesFolds rated turns into per-user preferencessession_ids, PERSONALIZATION_ENABLED=true (default false)
7build_truth_subspaceBuilds the truth subspace from distilled learningssession_ids, build_truth_subspace=True, a Ladybug graph
8triplet_enrichmentTriplet embeddings over the graph (memify)TRIPLET_EMBEDDING=true (default false), or custom tasks/data passed
9global_context_indexBucket and root summaries for global questionsbuild_global_context_index=True, an LLM

Stages 1–7 need session_ids; 8 and 9 work on the graph alone. The order matters: 4 feeds 5, 5 feeds 7, and 7 runs before 8.

Reading the result

improve() returns an ImproveResult, and so do POST /api/v1/improve, the CLI, and RememberResult.improve.

  • result.status: completed, errored (any stage errored), skipped (every stage skipped), or running (background, not finished).
  • result.stages: one StageResult per stage, with stage, status (completed / already_completed / skipped / errored), reason, error, counts, duration_ms.
  • result.stage("distill_sessions"), result.stage_summary(), result.lock_held, result.rerun_requested, result.rerun_passes.
  • await result.wait() finishes a background run (no-op otherwise).

Skip and no-op reasons:

ReasonMeaning / fix
no_session_idsSession stage, no session_ids passed
disabled_by_configListed in IMPROVE_STAGES_DISABLED
triplet_embedding_disabledSet TRIPLET_EMBEDDING=true to enable stage 8
opt_in_disabledPass build_truth_subspace=True / build_global_context_index=True
personalization_disabledSet PERSONALIZATION_ENABLED=true
auto_feedback_disabledStage 4 needs CACHING=true and AUTO_FEEDBACK=true
no_llm_configuredStages 4, 5, 9 draft text with an LLM; none configured
backend_unsupportedThe graph adapter lacks the feature (feedback weights, truth subspace)
session_manager_unavailableThe session cache is not reachable
lock_heldAnother improve for the same dataset or session is running (below)
aborted_by_fatal_stageStage 2 failed, so the rest did not run
budget_exhaustedAn earlier stage failed because the LLM budget is exhausted (a 402); the rest would fail the same way. Top up, then run improve again
no_new_entries, no_new_trace_steps, no_writes_since_last_improveWith status already_completed: nothing new since the last run
How remember() triggers improve
  • Without a session: add, then cognify, then a foreground improve(). Its outcome is on result.improve / result.improve_error. A failed improve never marks the remember as errored.
  • With session_id: the text is cached, then a background improve(dataset, session_ids=[session_id]) starts if the debounce allows it. result.improve fills in only after await result or wait_for_background_tasks().
  • self_improvement=False turns it off per call; IMPROVE_AUTO_ENABLED=false turns it off everywhere and overrides self_improvement=True.
  • An application embedding cognee can decline one automatic improve before it starts: cognee.modules.improve.register_auto_improve_admission(check) registers one async check that remember() awaits on both paths. Returning a reason string skips the improve and sets result.improve_skipped (result.improve stays None); the data is stored either way. A check that raises allows the improve. Explicit improve() calls are never gated.
Settings (IMPROVE_*, cognee/modules/improve/config.py)
Env varDefaultMeaning
IMPROVE_AUTO_ENABLEDtrueAutomatic improve after remember()
IMPROVE_DEBOUNCE_ENTRIES1Session auto-improve fires after this many new entries
IMPROVE_DEBOUNCE_SECONDS0...or this many seconds since the last one. Seconds alone (entries left at 1) means time-only
IMPROVE_STAGES_DISABLEDemptyCSV of stage names to skip
IMPROVE_FEEDBACK_ALPHA0.1Feedback learning rate, in (0, 1]

There is no debounce timer: held-back entries wait for the next remember() with that session, or an explicit improve().

Show full SKILL.md (602 more words)Show less

Pitfalls

  • A plain improve(dataset) often does nothing. Without session_ids, only stages 8 and 9 can run, and both are off by default. Result: every stage skipped. That is expected, not an error.
  • Typed entries do not auto-improve. remember(QAEntry/TraceEntry/ FeedbackEntry, session_id=...) stores the entry but never starts an improve. Call improve(session_ids=[...]) yourself.
  • lock_held does not wait. Improves for the same dataset or session run one at a time: a second call returns at once with every stage skipped: lock_held. If it shares a session with the running one, it sets rerun_requested=True and the holder runs up to 2 extra passes (3 passes in total; see rerun_passes). The bound is IMPROVE_MAX_RERUN_PASSES, a constant in cognee/api/v1/improve/improve.py, not an env var. The lock is per process only; multiple API workers do not share it.
  • Sessions bridge once. Q&A and trace persistence are tracked per user and session, not per dataset, so bridging a session into dataset A and then into dataset B persists no new Q&A/traces into B. Distillation is tracked per (session, dataset) and still runs into B.
  • IMPROVE_STAGES_DISABLED is validated. An unknown stage name, or persist_session_qa (fatal, cannot be disabled), raises ValueError, and the API server refuses to start.
  • Session writes with the cache off. remember(text, session_id=...) with CACHING=false only logs a warning and stores nothing; typed entries raise RuntimeError. An explicit improve(session_ids=...) then fails in the fatal stage.
  • Fatal stage failure. If stage 2 errors, improve() raises (HTTP 409) and the error carries .improve_result. In background mode it is recorded on result.error instead. Other stages failing only mark themselves errored; HTTP still returns 200, so check status.
  • Remote mode. After cognee.serve(url), a background improve is fire-and-forget: status stays running and there is no polling.
  • cognee/modules/session_bridge/ is gone (only stale __pycache__ may be left). The bridging now lives in the improve stages; some test names still say "session_bridge".

How it works

improve() resolves the dataset once (creating it if the name is new), claims the improve lock for dataset:<id> plus every session:<user>:<session_id>, probes the graph adapter's capabilities, and runs the stages with one frozen ImproveRunInputs. Each stage is a gate plus a call into existing pipelines plus a result mapping. Stages never own retries or ordering.

Watermarks keep repeat runs cheap:

  • Session stages track how many entries were already persisted, per user and session.
  • Stage 8 compares the last completed enrichment against later write pipelines for the dataset. A node_name or custom-task run bypasses that check.

The improve operation row is written when the run finishes: failed if any stage errored (a retry is never gated off), noop if nothing ran.

  • Orchestrator: cognee/api/v1/improve/improve.py (HTTP: routers/get_improve_router.py; CLI: cognee/cli/commands/improve_command.py)
  • Stages, registry, results: cognee/modules/improve/ (stages.py, registry.py, stage.py, result.py, inputs.py, capabilities.py, config.py, graph_changes.py, constants.py)
  • Lock: cognee/infrastructure/locks/session_lock.py
  • Session store and watermarks: cognee/infrastructure/session/ (session_manager.py, session_persist_watermark.py, feedback_detection.py); cache backends in cognee/infrastructure/databases/cache/
  • Auto-improve from remember: cognee/api/v1/remember/remember.py, cognee/api/v1/remember/auto_improve_debounce.py
  • Entry types: cognee/memory/entries.py
  • Background tasks: cognee/infrastructure/background_tasks.py

Examples: examples/guides/improve_quickstart.py, sessions.py, session_distillation.py, global_context_index.py, agent_memory_quickstart.py, and examples/advanced_guides/remember_recall_improve_example.py.

Extending it

Adding a stage:

  1. Subclass BaseStage in cognee/modules/improve/stages.py. Set name, needs_sessions, and fatal (leave it False; exactly one fatal stage is enforced at import). Implement gate() (return a skip reason constant, or None, before any LLM/embedding cost) and run() (call existing pipeline code, return a StageResult).
  2. Insert it into DEFAULT_STAGES in registry.py at the right position. The order is pinned by cognee/tests/unit/modules/improve/test_registry_order.py; update it deliberately.
  3. If it can re-run cheaply, give it a watermark so a repeat run reports already_completed.
  4. If it writes graph data under a new pipeline name, add that name to WRITE_PIPELINE_NAMES in graph_changes.py, or stage 8 will not notice the change.
  5. Tests: cognee/tests/unit/modules/improve/ (gates, results, config) and cognee/tests/unit/api/v1/improve/ (orchestration, rerun, router).

© topoteretes, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/cognee-improve-sessions of topoteretes/cognee.

Open the folder on GitHubat commit 0ec7a9f

Compare with similar skills

Cognee Session Memory and Improve next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Cognee Session Memory and Improve compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Cognee Session Memory and Improve this skilltopoteretes/cognee32k—~3.2kAutomated safety check: PassApache-2.0
Cortexdb Memory Hermesliliang-cn/cortexdb274—~1.7kAutomated safety check: PassMIT
Memori Long-Term MemoryMemoriLabs/Memori17k—~2kAutomated safety check: PassApache-2.0
Agent Memorytigerless-labs/agent-memory3.4k—~1.3kAutomated safety check: PassMIT
Hermes Memory Providersmnemosyne-oss/mnemosyne3.4k—~1.8kAutomated safety check: PassMIT
Cortexdb Memory Openclawliliang-cn/cortexdb274—~1.6kAutomated safety check: PassMIT

Similar skills

  • Cortexdb Memory Hermes

    liliang-cn/cortexdb

    Give a Python agent (such as Hermes Agent by Nous Research) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client…

    274 GitHub stars~1.7k tokensUpdated 3 days ago
    Knowledge ManagementAuto-check passed
  • Memori Long-Term Memory

    MemoriLabs/Memori

    Adds structured long-term memory to OpenClaw agents, built automatically from sessions, with tools the agent calls to recall facts, summaries and decisions.

    17k GitHub stars~2k tokensUpdated 8 days ago
    Agent WorkflowsAuto-check passed
  • Agent Memory

    tigerless-labs/agent-memory

    Read and write the shared long-term memory store. An agent skill from tigerless-labs/agent-memory.

    3.4k GitHub stars~1.3k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed
  • Hermes Memory Providers

    mnemosyne-oss/mnemosyne

    Install and configure Mnemosyne as a Hermes Agent memory provider — local SQLite with vector search, episodic consolidation, and temporal knowledge graphs.

    3.4k GitHub stars~1.8k tokensUpdated today
    AI & LLM EngineeringAuto-check passed
  • Cortexdb Memory Openclaw

    liliang-cn/cortexdb

    Give a Node.js agent (such as OpenClaw) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client npm package.

    274 GitHub stars~1.6k tokensUpdated 3 days ago
    Knowledge ManagementAuto-check passed
  • File-Based Planning in Arabic

    OthmanAdi/planning-with-files

    Arabic edition of a file-based planning skill that keeps task_plan.md, findings.md and progress.md on disk so multi-step agent work survives lost context.

    27k GitHub stars~3.2k tokensUpdated today
    Agent WorkflowsAuto-check: notes

More from topoteretes/cognee

All 19 skills in this repo
  • Cognee CLI Memory Commands

    topoteretes/cognee

    Drives cognee from the terminal with remember, recall, forget and improve memory commands, dataset and config management and database migrations.

    32k GitHub stars~2.2k tokensUpdated yesterday
    Auto-check: notes
  • Cognee Community Packages

    topoteretes/cognee

    Guide to using and contributing cognee community packages: database adapters, data-source connectors, custom tasks and retrievers, and Keywords AI observability.

    32k GitHub stars~1.2k tokensUpdated yesterday
    Auto-check passed
  • Cognee Custom Graph Models

    topoteretes/cognee

    Defines the shape of cognee's knowledge graph with graph_model: DataPoint node classes, identity and index fields, typed edges and fixes for duplicated nodes.

    32k GitHub stars~2.5k tokensUpdated yesterday
    Auto-check passed
  • Cognee Custom Pipelines

    topoteretes/cognee

    Shows how to write custom cognee tasks, chain them into pipelines, store custom DataPoints and run enrichment over the existing graph.

    32k GitHub stars~2.8k tokensUpdated yesterday
    Auto-check passed
  • Cognee Docker Setup

    topoteretes/cognee

    Runs the Cognee AI memory platform in Docker, from a one-file prebuilt image to a full compose stack with UI, MCP server, Postgres and Neo4j.

    32k GitHub stars~901 tokensUpdated yesterday
    Auto-check: notes
  • Cognee Forget

    topoteretes/cognee

    Removes data from cognee memory with forget(), finding the right dataset and document first and choosing between one document, a dataset or only the graph and vector memory.

    32k GitHub stars~1.9k tokensUpdated yesterday
    Auto-check passed

Questions about Cognee Session Memory and Improve

What does Cognee Session Memory and Improve do?

Explains how cognee stores session memory by session_id and bridges it into the permanent graph with improve(), including the stages, results and settings. This reference separates cognee's two kinds of memory: a fast session cache of conversation turns, agent traces and feedback keyed by session_id, and the permanent graph that remember() builds without a session.get_session() to read a session back.

When should I use Cognee Session Memory and Improve?

Cognee Session Memory and Improve fits situations like: storing conversation turns or agent traces under a session_id in cognee; working out why an improve() stage was skipped or reported lock_held; tuning the IMPROVE settings or the session cache backend and expiry.

How do I install Cognee Session Memory and Improve in Claude Code?

Run `npx skills add topoteretes/cognee --skill cognee-improve-sessions -a claude-code`. Or copy the skill folder (.agents/skills/cognee-improve-sessions in topoteretes/cognee) into .claude/skills/cognee-improve-sessions in your project. Claude Code loads it when a task matches its description.

How do I install Cognee Session Memory and Improve in Codex?

Run `npx skills add topoteretes/cognee --skill cognee-improve-sessions -a codex`. Or copy the skill folder (.agents/skills/cognee-improve-sessions in topoteretes/cognee) into .agents/skills/cognee-improve-sessions in your project. Codex loads it when a task matches its description.

Can I use Cognee Session Memory and Improve in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add topoteretes/cognee --skill cognee-improve-sessions -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/cognee-improve-sessions, .gemini/skills/cognee-improve-sessions, .github/skills/cognee-improve-sessions and .opencode/skills/cognee-improve-sessions in your project.

What does Cognee Session Memory and Improve need to run?

SKILL.md names no scripts, command-line tools or credentials: Cognee Session Memory and Improve is instructions for the agent only. Our summary lists: cognee installed in a Python project; Session caching enabled (the default).

Does Cognee Session Memory and Improve access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Cognee Session Memory and Improve safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Cognee Session Memory and Improve use?

Cognee Session Memory and Improve is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Cognee Session Memory and Improve use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Cognee Session Memory and Improve?

Skills that share tags, products or a category with Cognee Session Memory and Improve: Cortexdb Memory Hermes (liliang-cn/cortexdb, 274 stars), Memori Long-Term Memory (MemoriLabs/Memori, 17k stars), Agent Memory (tigerless-labs/agent-memory, 3.4k stars) and Hermes Memory Providers (mnemosyne-oss/mnemosyne, 3.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Cognee Session Memory and Improve?

topoteretes (a GitHub organization) maintains it in topoteretes/cognee, which has 31,919 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 9, 2026.

Source: topoteretes/cognee on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.