cognee

AutoGineer overview, from the brain’s own files

Memory model: Hybrid. Folders: .claude (agent config, 3 files); .github (agent config, 95 files); assets (attachments, 25 files); bin (scripts, 2 files); docs (docs, 13 files); examples (examples, 223 files); logs (logs, 2 files); scripts (scripts, 8 files). The agent reads pyproject.toml, .github/workflows/basic_tests.yml, query_type, cognee/api/v1/recall/query_router.py, tools. The agent writes examples/guides/, examples/README.md, cognee/api/v1/remember/remember.py, remove_dataset_routes, update_user_preferences.

The agent reads

• pyproject.toml evidence: AGENTS.md
• .github/workflows/basic_tests.yml evidence: AGENTS.md
• query_type evidence: CLAUDE.md
• cognee/api/v1/recall/query_router.py evidence: CLAUDE.md
• tools evidence: CLAUDE.md
• cognee/api/v1/improve/improve.py evidence: CLAUDE.md
• cognee/api/v1/forget/forget.py evidence: CLAUDE.md
• find_indexed_chunks evidence: CLAUDE.md
• cognee/modules/search/methods/search.py evidence: CLAUDE.md
• cognee/modules/search/dataset_routing/ evidence: CLAUDE.md
• cognee/modules/search/types/SearchType.py evidence: CLAUDE.md
• get_timestamps_in_range evidence: CLAUDE.md
• cognee/modules/operations/origin.py evidence: CLAUDE.md
• get_gliner_demo_tasks evidence: CLAUDE.md
• cognee/tests/e2e/remote_gliner/ evidence: CLAUDE.md
• cognee/api/v1/recall/skill_gate.py evidence: CLAUDE.md
• load_skill evidence: CLAUDE.md
• query_facts evidence: CLAUDE.md
• find_path evidence: CLAUDE.md
• cognee/modules/integrations/agent_identity.py evidence: CLAUDE.md

The agent writes

• examples/guides/ evidence: AGENTS.md
• examples/README.md evidence: AGENTS.md
• cognee/api/v1/remember/remember.py evidence: CLAUDE.md
• remove_dataset_routes evidence: CLAUDE.md
• update_user_preferences evidence: CLAUDE.md
• remove_document_index evidence: CLAUDE.md
• delete_data evidence: CLAUDE.md
• delete_edge_triples evidence: CLAUDE.md
• save_data_item_to_storage evidence: CLAUDE.md
• cognee/tasks/ingestion/ingest_data.py evidence: CLAUDE.md
• add_data_points evidence: CLAUDE.md
• cognee/api/v1/update/incremental.py evidence: CLAUDE.md
• create_root_summary_id evidence: CLAUDE.md
• create_document_bucket_id evidence: CLAUDE.md
• delete_collection evidence: CLAUDE.md
• upsert_raw_vectors evidence: CLAUDE.md
• create_data_points evidence: CLAUDE.md
• cognee/tasks/ evidence: CLAUDE.md
• cognee/modules/retrieval/ evidence: CLAUDE.md
• add_code_doc_edges evidence: CLAUDE.md

AutoGineer’s guidance for this type of brain

Install the library in your own agent code and call it to store and retrieve memories; see its documentation for the API.

Agent instructions that run or fetch something (239)

• .agents/skills/cognee-cli/SKILL.md: `--background`/`-b` runs the cognify stage in the background, and `--dry-run` estimates LLM tokens/cost without ingesting.
• .agents/skills/cognee-cli/SKILL.md: Both run automatically — at API server startup and on the first write (`remember`, `add`, `cognify`, `improve`, …) in an SDK/CLI process — unless `ENABLE_AUTO_MIGRATIONS=false`.
• .agents/skills/cognee-cli/SKILL.md: `forget` refuses to run bare — pass `--dataset`, `--dataset-id`, `--data-id` (with a dataset), or `--everything`/`--all`.
• .agents/skills/cognee-cli/SKILL.md: `config set`/`config unset` write to the `.env` file in whatever directory you run the command from (creating it if missing).
• .agents/skills/cognee-cli/SKILL.md: In a source/editable checkout (`uv pip install -e .`) a `.env` at the repo root therefore shadows the `.env` in the directory you ran from — and because `override=True`, it also beats variables you `export`ed.
• .agents/skills/cognee-cli/SKILL.md: (Under `python -c` the cwd `.env` does win, because dotenv falls back to the cwd when `__main__` has no `__file__` — which is why the same command can behave differently as a script vs.
• .agents/skills/cognee-community/SKILL.md: Install, then **import the package's `register` module before cognee touches any engine** — registration is what makes the provider name valid:
• .agents/skills/cognee-community/SKILL.md: uv pip install cognee-community-vector-adapter-qdrant
• .agents/skills/cognee-community/SKILL.md: Every package has `examples/example.py` (run `uv run python examples/example.py` from the package dir) and a `tests/` directory.
• .agents/skills/cognee-community/SKILL.md: Follow the existing structure: package dir under `packages/<family>/<name>/` with `pyproject.toml`, a `README.md` (install + usage), `examples/example.py`, and `tests/` that go beyond the example.
• .agents/skills/cognee-community/SKILL.md: New DB adapters implement `VectorDBInterface` / `GraphDBInterface` from core, expose a `register.py`, and should run the shared conformance tests in `packages/shared/contract_suite/` (vector_contract.py / graph_contract.py).
• .agents/skills/cognee-custom-graph-models/SKILL.md: **Without `identity_fields` every node gets a random id, so the same person is duplicated in every chunk and every run.** Set it on every node type that represents a real-world entity.
• .agents/skills/cognee-custom-graph-models/SKILL.md: Endpoints resolve by **exact type** against nodes extracted from the same chunk: a subclass instance does not match where its base is declared, and a node from another chunk or an earlier run is not a candidate.
• .agents/skills/cognee-custom-graph-models/SKILL.md: Summaries still run.
• .agents/skills/cognee-custom-pipelines/SKILL.md: | Runner | Import | Use it for | |---|---|---| | `cognee.run_custom_pipeline(...)` | `cognee` | The normal choice: runs your tasks against a dataset with permissions, a per-dataset lock, run records, and status | | Full orchestrator `run_pipeline(tasks=..., data=..., datasets=...)` | `c …[+73 chars]
• .agents/skills/cognee-custom-pipelines/SKILL.md: yields `PipelineRunInfo` | | Lightweight `run_pipeline([...], data=...)` | `from cognee.pipelines import run_pipeline` (after `import cognee`, the attribute `cognee.pipelines.run_pipeline` is the orchestrator) | Quick chains of `task()` specs with no permissions, locks, run rows, or migrations;
• .agents/skills/cognee-custom-pipelines/SKILL.md: `cognee.run_custom_pipeline(tasks, data=None, dataset="main_dataset", user=None, incremental_loading=False, data_per_batch=20, run_in_background=False, pipeline_name="custom_pipeline", data_cache=False, ...)` returns `{dataset_id: PipelineRunInfo}` (the started run when `run_in_background=True`).
• .agents/skills/cognee-custom-pipelines/SKILL.md: **`data_per_batch`** (default 20) is how many documents run at the same time.
• .agents/skills/cognee-custom-pipelines/SKILL.md: **Streaming:** each upstream result goes down the chain immediately, so a downstream task can run many times per document.
• .agents/skills/cognee-custom-pipelines/SKILL.md: Run a post-processing step over the graph with `run_custom_pipeline`: the task reads the graph itself, and one placeholder item as `data` makes the chain run once instead of once per document.
• .agents/skills/cognee-custom-pipelines/SKILL.md: **`run_custom_pipeline` does not run database migrations.** On an existing database, run `await cognee.run_migrations()` (or any `remember()` first).
• .agents/skills/cognee-custom-pipelines/SKILL.md: **Nodes duplicate on every run** when a DataPoint has no `identity_fields` (or `Dedup()` fields).
• .agents/skills/cognee-docker/SKILL.md: docker compose up
• .agents/skills/cognee-docker/SKILL.md: curl http://localhost:8000/health · uses the network
• .agents/skills/cognee-docker/SKILL.md: curl -X POST http://localhost:8000/api/v1/remember -F "[email protected]" -F "datasetName=main_dataset" · uses the network
• .agents/skills/cognee-docker/SKILL.md: curl -X POST http://localhost:8000/api/v1/recall -H "Content-Type: application/json" \ · uses the network
• .agents/skills/cognee-docker/SKILL.md: docker compose up # API server only, port 8000
• .agents/skills/cognee-docker/SKILL.md: docker compose --profile ui up # + frontend on port 3000
• .agents/skills/cognee-docker/SKILL.md: docker compose --profile mcp up # + MCP server on port 8001
• .agents/skills/cognee-docker/SKILL.md: docker compose --profile postgres --profile neo4j up # + databases
• .agents/skills/cognee-forget/SKILL.md: For a byte-level erasure guarantee run the engine's own compaction or vacuum, or start a new store.
• .agents/skills/cognee-improve-sessions/SKILL.md: Every run goes through the same ordered stages (`cognee/modules/improve/registry.py`).
• .agents/skills/cognee-improve-sessions/SKILL.md: `extraction_tasks` / `enrichment_tasks` are deprecated and removed in the next release: they still run, as a `custom_tasks` stage after the others, scoped by `node_name`, `data`, `node_type`, `vector_db_config` and `graph_db_config`.
• .agents/skills/cognee-improve-sessions/SKILL.md: `await result.wait()` finishes a background run (no-op otherwise).
• .agents/skills/cognee-improve-sessions/SKILL.md: none configured | | `edge_evidence_disabled` | Conflict review needs `EDGE_EVIDENCE_ENABLED=true` | | `backend_unsupported` | The graph adapter lacks the feature (feedback weights, truth subspace) | | `session_manager_unavailable` | The session cache is not reachable | | `aborted_by_fa …[+146 chars]
• .agents/skills/cognee-improve-sessions/SKILL.md: Top up, then run improve again | | `no_new_entries`, `no_new_trace_steps`, `no_new_facts`, `no_writes_since_last_improve` | With status `already_completed`: nothing new since the last run |
• .agents/skills/cognee-improve-sessions/SKILL.md: **A plain `improve(dataset)` often does nothing.** Without `session_ids`, only stages 8–9 can run, and both are off by default.
• .agents/skills/cognee-improve-sessions/SKILL.md: **Improves queue.** An improve holds the dataset's lock for its whole run, like `cognify()`: improves, cognify, add and forget on one dataset run one at a time, and improves sharing a session also wait for each other.
• .agents/skills/cognee-improve-sessions/SKILL.md: 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.
• .agents/skills/cognee-improve-sessions/SKILL.md: Implement `gate()` (return a skip reason constant, or `None`, before any LLM/embedding cost) and `run()` (call existing pipeline code, return a `StageResult`).
• .agents/skills/cognee-improve-sessions/SKILL.md: If it can re-run cheaply, give it a watermark so a repeat run reports `already_completed` (graph-wide stages can stamp the improve row with the helpers in `watermarks.py`, as conflict review does).
• .agents/skills/cognee-ingestion/SKILL.md: `extractor="gliner"` builds the graph and summaries with a local GLiNER2 model, with no LLM call (embeddings still run).
• .agents/skills/cognee-ingestion/SKILL.md: Install `pip install "cognee[gliner]"`;
• .agents/skills/cognee-ingestion/SKILL.md: **New loader:** implement `LoaderInterface` (`cognee/infrastructure/loaders/LoaderInterface.py`), register it in `supported_loaders.py` (extras-gated loaders go under `external/`), and add it to the priority list in `LoaderEngine.py` if it should run by default.
• .agents/skills/cognee-install/SKILL.md: asyncio.run(main())
• .agents/skills/cognee-integrations/SKILL.md: Install the matching extra before switching a backend (e.g. `pip install cognee[postgres]`).
• .agents/skills/cognee-integrations/SKILL.md: Anything else (ChromaDB, Qdrant, Weaviate, Milvus, …) lives in community adapters — install from https://github.com/topoteretes/cognee-community and register with `use_vector_adapter` before use;
• .agents/skills/cognee-integrations/SKILL.md: `docker compose --profile mcp up` starts the MCP server on port 8001 (Streamable HTTP at `http://localhost:8001/mcp`), built from `cognee-mcp/`.
• .agents/skills/cognee-migrations/SKILL.md: cognee has **two migration chains**, run together:
• .agents/skills/cognee-migrations/SKILL.md: At head, the first run in each process still does a no-op Alembic upgrade plus a scan of the per-database revision rows;
• .agents/skills/cognee-migrations/SKILL.md: then run `cognee-cli upgrade` yourself.
• .agents/skills/cognee-migrations/SKILL.md: Run `cognee-cli current` to see the error, fix the cause, then `cognee-cli upgrade`.
• .agents/skills/cognee-migrations/SKILL.md: A failed run is retried on the next start or write.
• .agents/skills/cognee-migrations/SKILL.md: uv run alembic revision -m "add foo to data"
• .agents/skills/cognee-performance/SKILL.md: **The LLM is the bottleneck.** Building the graph costs two LLM calls per chunk (graph extraction and summarization), and almost every other tuning question comes down to how many of those calls run, how fast, and on which model.
• .agents/skills/cognee-performance/SKILL.md: Several datasets in one `cognify(datasets=[...])` call run one after another, not in parallel.
• .agents/skills/cognee-performance/SKILL.md: `remember(data, extractor="gliner")` builds the graph and summaries with a local GLiNER model: no LLM calls, embeddings still run.
• .agents/skills/cognee-performance/SKILL.md: then `pip install "cognee[gliner]"`).
• .agents/skills/cognee-performance/SKILL.md: `remember()` → `add()` → `cognify()`: every document of the dataset is scheduled at once, `data_per_batch` of them run concurrently, and each runs the task chain (classify, chunk, extract graph + summarize, store).
• .agents/skills/cognee-performance/SKILL.md: Retrieval quality and cost: `cognee/eval_framework/` (`python -m cognee.eval_framework`;
• .agents/skills/cognee-permissions/SKILL.md: Without `user=`, SDK calls run as the default user (`[e-mail address: https://github.com/topoteretes/cognee]`, or `DEFAULT_USER_EMAIL`).
• .agents/skills/cognee-permissions/SKILL.md: ACL checks still run, but they only gate which dataset ids may be named: retrieval runs over the shared graph and vector databases, so other users' content is not filtered out.
• .agents/skills/cognee-recall/SKILL.md: With no usable LLM key nothing can write an answer, so on both paths `HYBRID_COMPLETION`, `GRAPH_COMPLETION` and `RAG_COMPLETION` run with `only_context=True` (the assembled prompt instead of an answer), and a routed `TEMPORAL` or `BROAD` becomes `HYBRID_COMPLETION` with `only_context=True`;
• .agents/skills/cognee-server/SKILL.md: For API-only serving via Docker instead, use the cognee-docker skill (the prebuilt `cognee/cognee:main` image or `docker compose up` from the repo).
• .agents/skills/company-brain-company-qa/SKILL.md: Run every command from the repo root.
• .agents/skills/company-brain-company-qa/SKILL.md: If they have none, or want to see it work first, pass no sources: the run then uses the sample company (the `[setup]` line says so).
• .agents/skills/company-brain-company-qa/SKILL.md: Run `uv run python examples/cookbooks/company_brain/company_qa/company_qa.py --check` with the sources (`--database URL [--tables a,b] --tickets FILE [FILE ...] --docs FOLDER`), or none for the sample.
• .agents/skills/company-brain-company-qa/SKILL.md: Run the same command without `--check`, adding the user's question as `--ask "..."`.
• .agents/skills/company-brain-company-qa/SKILL.md: Run that script from `examples/cookbooks/company_brain/company_qa/scripts/` on its own to look closer.
• .agents/skills/company-brain-company-qa/SKILL.md: Every run uses LLM credits, so ingest only when the user asked for it.
• .agents/skills/company-brain-company-qa/SKILL.md: A sample run forgets the cookbook's dataset `company_qa` before it ingests (the `[clear]` line).
• .agents/skills/company-brain-company-qa/SKILL.md: uv run cognee-cli forget --dataset company_qa
• .agents/skills/company-brain-follow-up-agent/SKILL.md: Run every command from the repo root.
• .agents/skills/company-brain-follow-up-agent/SKILL.md: With none of Granola, Linear and Gmail set up, the commands below run on sample calls, issues and email (the `[setup]` line says so), follow up a fictional call and never post to Slack;
• .agents/skills/company-brain-follow-up-agent/SKILL.md: Run `uv run python examples/cookbooks/company_brain/follow_up_agent/follow_up_agent.py --check`.
• .agents/skills/company-brain-follow-up-agent/SKILL.md: Run `uv run python examples/cookbooks/company_brain/follow_up_agent/follow_up_agent.py`.
• .agents/skills/company-brain-follow-up-agent/SKILL.md: Run that script from `examples/cookbooks/company_brain/follow_up_agent/scripts/` on its own to look closer.
• .agents/skills/company-brain-follow-up-agent/SKILL.md: With Slack set up, a run posts to the user's real channel, and every run reads the user's real calls, issues and mailbox and uses LLM credits, so run it only when the user asked for it.
• .agents/skills/company-brain-follow-up-agent/SKILL.md: A sample run forgets the cookbook's dataset `follow_up_agent` before it ingests (the `[clear]` line).
• .agents/skills/company-brain-follow-up-agent/SKILL.md: uv run cognee-cli forget --dataset follow_up_agent
• .agents/skills/google-workspace-memory/SKILL.md: Run every command from the repo root.
• .agents/skills/google-workspace-memory/SKILL.md: Without `credentials.json` in the cookbook folder, the commands below run on a sample workspace (the `[setup]` line says so) and answer about a fictional ceramics business;
• .agents/skills/google-workspace-memory/SKILL.md: Run `uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py --check`.
• .agents/skills/google-workspace-memory/SKILL.md: If only `GOOGLE_DRIVE_FOLDER_ID` is missing, ask whether to run with `--no-drive` instead.
• .agents/skills/google-workspace-memory/SKILL.md: Run `uv run python examples/cookbooks/google_workspace_memory/google_workspace_memory.py`.
• .agents/skills/google-workspace-memory/SKILL.md: The first run opens the browser once per app for consent;
• .agents/skills/google-workspace-memory/SKILL.md: If a run stops after `--check` passed, the last `[<step>]` line (or the traceback) says why.
• .agents/skills/google-workspace-memory/SKILL.md: For a follow-up question on the same data, run `uv run python examples/cookbooks/google_workspace_memory/scripts/ask.py --ask "..."`, with `--sample` if the first run was on the sample;
• .agents/skills/google-workspace-memory/SKILL.md: A sample run forgets the sample's dataset `google_workspace_memory_sample` before it ingests (the `[clear]` line).
• .agents/skills/google-workspace-memory/SKILL.md: Ingesting reads the user's real calendar, mailbox and Drive files, and every run uses LLM credits.
• .agents/skills/google-workspace-memory/SKILL.md: The first run cognifies the whole primary calendar, which can take ten minutes or more, so tell the user before you start it and run it only when they asked for it.
• .agents/skills/google-workspace-memory/SKILL.md: uv run cognee-cli forget --dataset google_workspace_memory
• .agents/skills/google-workspace-memory/SKILL.md: uv run cognee-cli forget --dataset google_workspace_memory_sample
• .agents/skills/multiagent-memory-setup/SKILL.md: Run every command from the repo root.
• .agents/skills/multiagent-memory-setup/SKILL.md: When the user has no Claude Code or Codex history, or wants to see it work first, run the demo instead of the steps below.
• .agents/skills/multiagent-memory-setup/SKILL.md: It is what the cookbook runs without `--agents`: `uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py` (`--check` first to check the key;
• .agents/skills/multiagent-memory-setup/SKILL.md: Run `uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py --check`.
• .agents/skills/multiagent-memory-setup/SKILL.md: Run the import with `--agents` set to the user's choice, like `--agents claude,codex`, and one `--project <path>` per chosen project, copying the path from its `Project:` line (leave `--project` out for all projects).
• .agents/skills/multiagent-memory-setup/SKILL.md: without one the run asks "What did I work on in these sessions?": `uv run python examples/cookbooks/import_agent_sessions/import_agent_sessions.py --agents <choice> --project <path> --ask "..."`.
• .agents/skills/multiagent-memory-setup/SKILL.md: If a step fails, the run exits 1 and the traceback's last line says why.
• .agents/skills/multiagent-memory-setup/SKILL.md: Run that script from `examples/cookbooks/import_agent_sessions/scripts/` on its own to look closer.
• .agents/skills/multiagent-memory-setup/SKILL.md: Every imported session is sent to the provider of the key cognee runs on and costs LLM calls, so run the import only when the user asked for it, and raise `--limit` only when they want more history.
• .agents/skills/multiagent-memory-setup/SKILL.md: uv run cognee-cli forget --dataset imported_agent_sessions
• .agents/skills/multiagent-memory-setup/SKILL.md: uv run cognee-cli forget --dataset imported_agent_sessions_demo
• .agents/skills/personalized-email/SKILL.md: Run every command from the repo root.
• .agents/skills/personalized-email/SKILL.md: With neither Gmail nor Granola set up, the commands below run on a sample mailbox (the `[setup]` line says so) and draft a reply to a fictional email;
• .agents/skills/personalized-email/SKILL.md: Run `uv run python examples/cookbooks/personalized_email/personalized_email.py --check`.
• .agents/skills/personalized-email/SKILL.md: If only the Granola line is missing, ask whether to run with `--no-granola` instead.
• .agents/skills/personalized-email/SKILL.md: Run `uv run python examples/cookbooks/personalized_email/personalized_email.py`.
• .agents/skills/personalized-email/SKILL.md: Run that script from `examples/cookbooks/personalized_email/scripts/` on its own to look closer.
• .agents/skills/personalized-email/SKILL.md: A sample run forgets the cookbook's dataset `personalized_email` before it ingests (the `[clear]` line).
• .agents/skills/personalized-email/SKILL.md: Ingesting reads the user's real meetings and mailbox, and every run uses LLM credits, so run it only when the user asked for it.
• .agents/skills/personalized-email/SKILL.md: uv run cognee-cli forget --dataset personalized_email
• .agents/skills/self-hosted-companion/SKILL.md: Run every command from the repo root.
• .agents/skills/self-hosted-companion/SKILL.md: Without a notes folder of the user's own, or to see it work first, leave out `<folder>` below: the run then uses sample notes (the `[setup]` line says so).
• .agents/skills/self-hosted-companion/SKILL.md: Run `uv run python examples/cookbooks/self_hosted_companion/self_hosted_companion.py --check <folder>` with the notes folder the user named.
• .agents/skills/self-hosted-companion/SKILL.md: You can't type into the interactive chat, so pass the user's message with `--ask`: `uv run python examples/cookbooks/self_hosted_companion/self_hosted_companion.py <folder> --ask "..."`.
• .agents/skills/self-hosted-companion/SKILL.md: Once the folder is remembered, later messages only need `uv run python examples/cookbooks/self_hosted_companion/scripts/chat.py --ask "..."`.
• .agents/skills/self-hosted-companion/SKILL.md: Run that script from `examples/cookbooks/self_hosted_companion/scripts/` on its own to look closer.
• .agents/skills/self-hosted-companion/SKILL.md: Every run uses LLM credits, so run it only when the user asked for it.
• .agents/skills/self-hosted-companion/SKILL.md: A sample run forgets the cookbook's dataset `self_hosted_companion` before it ingests (the `[clear]` line).
• .agents/skills/self-hosted-companion/SKILL.md: uv run cognee-cli forget --dataset self_hosted_companion
• AGENTS.md: Create/refresh env and install dev deps:
• AGENTS.md: Run the CLI (examples).
• AGENTS.md: Run tests (CI mirrors these commands):
• AGENTS.md: Install and run locally:
• AGENTS.md: Turso: the three layers and the session cache (`CACHE_BACKEND=turso`) can run on the Turso rewrite engine (`pyturso`, local files only);
• AGENTS.md: set `ENABLE_BACKEND_ACCESS_CONTROL=false` to run such backends single-tenant.
• AGENTS.md: PRs should describe scope, list local test commands run, and mention any impacts on MCP server or UI if applicable.
• AGENTS.md: Our GitHub Actions run the same ruff checks and pytest suites shown above (`.github/workflows/basic_tests.yml` and related workflows).
• CLAUDE.md: **docling-full** - Full docling install with torch-based ML models (adds PDF/image conversion through docling)
• CLAUDE.md: # Run all tests
• CLAUDE.md: # Run with coverage
• CLAUDE.md: # Run specific test file
• CLAUDE.md: # Run specific test function
• CLAUDE.md: # Run async tests
• CLAUDE.md: # Run unit tests only
• CLAUDE.md: # Run integration tests only
• CLAUDE.md: # Run ruff linter
• CLAUDE.md: # Run ruff formatter
• CLAUDE.md: # Run both linting and formatting (pre-commit)
• CLAUDE.md: pre-commit run --all-files
• CLAUDE.md: uv run python examples/guides/simple_cognee_example.py
• CLAUDE.md: **improve()** - Run the self-improvement stages over a dataset: with `session_ids`, bridge session Q&A, agent traces, distilled learnings and user preferences into the permanent graph and apply feedback weights;
• CLAUDE.md: named or given tasks still run, a call with no tasks checks the dataset and runs nothing), `cognee-cli memify` (prints the notice and exits: it cannot name tasks), `improve(extraction_tasks=..., enrichment_tasks=...)` and `POST /api/v1/improve`'s `extractionTasks` / `enrichmentTasks` (u …[+27 chars]
• CLAUDE.md: the tasks still run after the stages, as an extra `custom_tasks` stage, on the first pass only), `SearchType.TRIPLET_COMPLETION` (runs as `GRAPH_COMPLETION`), `ImproveResult.memify_run` (the first pass's `custom_tasks` raw return, else `{}`;
• CLAUDE.md: Tasks are composable units that can run sequentially or in parallel.
• CLAUDE.md: Abandoned-run recovery checks at API startup and every 60 seconds.
• CLAUDE.md: Each new pipeline run holds an OS lock under `SYSTEM_ROOT_DIRECTORY/pipeline_run_locks` from its persisted start through its terminal record, including the background handoff.
• CLAUDE.md: Recovery must acquire the existing ownership marker and re-read the latest run status before rolling back.
• CLAUDE.md: The pin is read strictly: a session whose cache cannot be read is never treated as unpinned, so a pin is refused rather than overwritten and the bridging stages skip that session for the run instead of adding it untagged (the extractors take one strict snapshot per session for both the …[+31 chars]
• CLAUDE.md: `extraction_tasks` / `enrichment_tasks` are deprecated: they run as a `custom_tasks` stage appended after the registry stages, and `node_name`, `data`, `node_type`, `vector_db_config` and `graph_db_config` scope them.
• CLAUDE.md: `run()` returns a `StageResult` whose `status` reuses `PipelineRunInfo`'s vocabulary — `completed`, `already_completed` (nothing new since the stage's watermark), `errored` — plus `skipped`.
• CLAUDE.md: every other failure is recorded as `errored` and the run continues.
• CLAUDE.md: One failure is run-wide instead: a stage that errors because the LLM budget is exhausted (`LLMPaymentRequiredError`, HTTP 402;
• CLAUDE.md: `StageResult.budget_exhausted` classifies both a raised error and a `PipelineRunErrored` a stage's pipeline only reported) stops the run, since every later stage would fail the same way — the remaining stages are `skipped: budget_exhausted`.
• CLAUDE.md: The stage that hit it stays `errored` and so does the run;
• CLAUDE.md: when it is the fatal stage the run still raises, with `budget_exhausted` instead of `aborted_by_fatal_stage` on the stages it cut off.
• CLAUDE.md: The run resolves the dataset once and hands every stage a frozen `ImproveRunInputs` (user, resolved dataset id, session ids, `ImproveConfig`, adapter `GraphCapabilities`).
• CLAUDE.md: It holds the per-dataset lock for the whole run, exactly like a pipeline run, so improve, cognify, add and forget on one dataset queue one after another (process-local, like that lock);
• CLAUDE.md: A background run returns at once and waits inside its task.
• CLAUDE.md: the row is written when the run finishes — deferred to the background task in background mode — with a failed outcome when any stage errored (so a retry is never gated off) and a `noop` outcome when nothing ran — an all-skipped run — so a no-op call never advances the watermark.
• CLAUDE.md: The `global_context_index` stage reports `already_completed` only when nothing but a search, a recall or a `noop` improve (one that ran no stage) has run on the dataset since its stamp, whatever the pipeline or outcome (so a failed write and a `forget` count too), because its text must …[+18 chars]
• CLAUDE.md: with backend access control off, any other dataset's run counts too.
• CLAUDE.md: Feedback-weight application records applied element ids per QA row so a deleted node no longer causes the same feedback to be re-applied on every run;
• CLAUDE.md: a value caps the steps per document) and `IMPROVE_TRACE_WINDOWS_PER_RUN` (default 0: one run drains the backlog it started with, windows ending at each session's starting step count so steps written meanwhile wait for the next run;
• CLAUDE.md: a value caps the windows per run).
• CLAUDE.md: A host application can also decline a single automatic improve before it starts: `cognee.modules.improve.register_auto_improve_admission(check)` registers one async check per process (a later registration replaces it, `None` / `clear_auto_improve_admission()` removes it) that `remember …[+217 chars]
• CLAUDE.md: Later runs review touched entities, showing only the value groups and statement pairs that gained a fact since the last review (a run that retries a failed entity shows everything), and repair conflicts with missing citations or pending writes;
• CLAUDE.md: `EARLY_CHUNK_INDEXING=false` or `cognify(early_chunk_indexing=False)` skips the run).
• CLAUDE.md: The cognify run opens first and is the one callers follow (its run id, its events);
• CLAUDE.md: the indexing run works between its start and its tasks under the same dataset lock.
• CLAUDE.md: `update()`'s incremental path refuses a baseline whose chunks were written by a run that never completed, or whose document has no cognify completion stamp (`no_baseline`), so entity-less chunks never seed an incremental update.
• CLAUDE.md: `cognify()` runs `reconcile_document_structure` (`cognee/tasks/ingestion/document_structure.py`) as the `after_items_ran` hook of `run_pipeline`: awaited when the run completed and also when items in it failed (reported or raised), ahead of the `after_run_completed` vector compaction, …[+283 chars]
• CLAUDE.md: With `raise_on_error=False` (`POST /api/v1/cognify` included) nothing is raised: each failed dataset's completed run carries the reason as `after_run_error`.
• CLAUDE.md: `update()` reports it as `after_run_error` on its result, as it does a failed run;
• CLAUDE.md: improve's session, trace and distillation bridges first advance their watermarks (the data is stored, so the LLM work is not repeated) and raise it after, which records their stage as `errored` (it does not stop the run, not even from the fatal `persist_session_qa`).
• CLAUDE.md: On a failed run the run's own error wins: a raised one is kept with the hook's error as its `__cause__`, a reported one is returned and the hook's error is logged.
• CLAUDE.md: It reconciles the whole dataset, not the run's items, without an LLM: `child_of` edges (child to parent) between Document nodes, the parent found by `external_id` within source + `table_name` + dataset, and `StructureContainer` nodes for ancestors without a row (a Notion database or data source;
• CLAUDE.md: only a region's last chunk may be under-filled), replaced chunks (plus their summaries, chunk-orphaned entities, and legacy triplet embeddings) are deleted, and only the new chunks run through LLM extraction.
• CLAUDE.md: **No key at all** is also a working setup: with no LLM and no embedding credentials configured, cognify extracts the graph with the local GLiNER demo model (`pip install "cognee[gliner]"` recommended;
• CLAUDE.md: both models are kept in the Hugging Face hub cache, default `~/.cache/huggingface/hub`, which `HF_HOME` moves for both, with `FASTEMBED_CACHE_PATH` overriding it for fastembed alone), and `recall()` without a `query_type` routes only to search types that run without an LLM, defaulting t …[+91 chars]
• CLAUDE.md: # PostgreSQL (requires postgres extra: pip install cognee[postgres])
• CLAUDE.md: Others (ChromaDB, Qdrant, Weaviate, Milvus, …) are community adapters — install from https://github.com/topoteretes/cognee-community and register via `use_vector_adapter` before setting `VECTOR_DB_PROVIDER`, otherwise cognee raises "Unsupported vector database provider".
• CLAUDE.md: # Neo4j (requires neo4j extra: pip install cognee[neo4j])
• CLAUDE.md: # Postgres (requires postgres extra: pip install cognee[postgres])
• CLAUDE.md: `DB_PROVIDER=turso`, `GRAPH_DATABASE_PROVIDER=turso`, `VECTOR_DB_PROVIDER=turso` and `CACHE_BACKEND=turso` (the session cache's `cache.db`, same layout as the sqlite backend) — all four layers — run on the Turso rewrite engine (`pyturso`, `pip install cognee"[turso]"`) through one share …[+79 chars]
• CLAUDE.md: # Or use Instructor (legacy, via litellm; requires instructor extra: pip install cognee[instructor])
• CLAUDE.md: # Or use BAML (requires baml extra: pip install cognee[baml])
• CLAUDE.md: # S3 (requires aws extra: pip install cognee[aws])
• CLAUDE.md: `ONTOLOGY_REASONING=owl_rl` runs an OWL 2 RL deductive closure (via the optional `owlrl` package, `pip install cognee[ontology]`) over the parsed ontology before the lookup is built, so `owl:inverseOf`, `rdfs:domain`/`rdfs:range` typing, `owl:equivalentClass`, `owl:sameAs` and transitiv …[+62 chars]
• CLAUDE.md: git checkout dev
• CLAUDE.md: git pull origin dev · uses the network
• CLAUDE.md: git checkout -b feature/your-feature-name
• CLAUDE.md: **Pre-commit hooks**: Run ruff linting and formatting automatically
• CLAUDE.md: **Important**: Always run `pre-commit run --all-files` before committing to catch formatting issues
• CLAUDE.md: Tests are organized in `cognee/tests/` (layout, credentials per folder, and how to run without API keys: `cognee/tests/README.md`;
• CLAUDE.md: `e2e/` - Full-stack end-to-end suites run per backend in CI (e.g. `e2e/incremental_update/` runs on LadybugDB + LanceDB, Postgres graph + PGVector, and Neo4j + LanceDB;
• CLAUDE.md: All functions are async - use `await` or `asyncio.run()`.
• CLAUDE.md: Off by default because raw Cypher lets any user with read access run arbitrary queries, up to remote code execution;
• CLAUDE.md: `GRAPH_EXTRACTOR` defaults to **auto**: the LLM path when a usable LLM key is configured (`llm_available()`), the GLiNER demo when none is — so a fresh install with no credentials ingests on local models, and the moment `LLM_API_KEY` is set the pipeline is the LLM one, unchanged.
• CLAUDE.md: embeddings in `add_data_points` still run — on keyless setups via the fastembed default (`resolve_embedding_defaults()` in `cognee/infrastructure/databases/vector/embeddings/config.py`: no embedding setting configured + no usable LLM key → `fastembed` / `BAAI/bge-small-en-v1.5`, vector …[+42 chars]
• CLAUDE.md: **Install**: recommended `pip install "cognee[gliner]"` (torch from PyPI: the CUDA build on Linux, for GPU hosts).
• CLAUDE.md: concurrent callers in one process or several wait on one install — and it installs the `gliner` extra itself (read from cognee's metadata, so `pyproject.toml` is the only list), with progress logged (step, installer lines, elapsed time): its torch requirement only when no torch build ( …[+146 chars] · uses the network
• CLAUDE.md: then the rest, when `gliner2` is missing, from the default index with every installed distribution pinned — a package replaced under a live import would break the running process, so an install that needs to change one fails instead (core pins `huggingface-hub<1` and `tokenizers<=0.23.0 …[+48 chars]
• CLAUDE.md: It uses pip, or `uv pip` in uv venvs, under a file lock in `sys.prefix`, and logs a one-line tip to install the extra afterwards.
• CLAUDE.md: The install thread imports torch and gliner2 before returning (verification, and it keeps the slow first import off the loop).
• CLAUDE.md: Telemetry: `GLiNER Runtime Install Started` / `Completed` / `Failed`, sent only by the call that installs, with versions, OS/arch, installer, installed packages, duration, and on failure the step and exception class — never paths, URLs, installer output or messages (a custom index is re …[+20 chars]
• CLAUDE.md: The Docker image runs the installer at build time (`python -m cognee.tasks.graph.gliner_demo.install`, after the exact `uv sync`).
• CLAUDE.md: A later exact `uv sync` removes the runtime-installed packages (they are not in the lockfile);
• CLAUDE.md: **LLM-free mode side effects**: a pipeline with no LLM task (the gliner_demo extractor) skips the first-run LLM connection probe but still probes embeddings, per capability — an LLM-free run never marks the LLM check done for later LLM runs.
• CLAUDE.md: session and trace persistence still run, and so does `global_context_index`, whose default method counts entities instead of prompting.
• CLAUDE.md: Separately, with no usable LLM key `recall()` still auto-routes, but only to search types that run without an LLM: retrieval-only types run as they are, the completion types whose single LLM call is the final answer (`HYBRID_COMPLETION`, `GRAPH_COMPLETION`, `RAG_COMPLETION`) run with ` …[+205 chars]
• CLAUDE.md: a worker without windowing fails the run (`/readyz` `features`, or a reply's `windowed` flag over gRPC/RabbitMQ).
• CLAUDE.md: One `RemoteGlinerAdapter` per run, built and readiness-checked in `get_gliner_demo_tasks`;
• CLAUDE.md: a loop's transports close when it shuts down (`shutdown_asyncgens`, which `asyncio.run` and uvicorn run).
• CLAUDE.md: once spent, it — like bad credentials, the wrong model (`COGNEE_GLINER_EXPECTED_MODEL`, or an explicit `model_name`: without one the worker's model is accepted), or an endpoint that is not a compatible worker (readiness that does not answer like one, no windowing) — is latched and fail …[+140 chars]
• CLAUDE.md: over gRPC only this client's own deadline, a proxy's earlier `DEADLINE_EXCEEDED` is retried like an HTTP 504) is not resent, since the worker may still run it: it fails its document after a fresh readiness check, which fails the run instead when the worker is gone.
• CLAUDE.md: Dataset-scoped `SKILL.md` playbooks agents can discover, load on demand, execute, and improve from run history.
• CLAUDE.md: **Execute**: `SearchType.AGENTIC_COMPLETION` with `skills=[...]` — LLM sees name+description, loads bodies via the `load_skill` tool (12k char cap).
• CLAUDE.md: **Improve**: `SkillRun` records (via `remember()` skill-run entries) feed LLM-drafted `SkillImprovementProposal`s;
• CLAUDE.md: Same option over REST (`code_query` on `POST /api/v1/search` and `/api/v1/recall` with `scope=["code"]`) and the CLI: `cognee-cli search "" -t CODE --code-query '{"operation": "architecture"}' --diagram-out arch.html` (`.html` renders Mermaid in a browser, `.svg/.png/.pdf` run Graphviz …[+40 chars]
• CLAUDE.md: each `flows.json` flow becomes a `CodeFlow` node with `flow_entry`/`flow_stage`/`flow_route` edges to its entry, stages and routes, but only when the receipt lists that `flows.json` among the run's outputs (a release without the flows renderer leaves an earlier run's file in place;
• CLAUDE.md: Its `code_repo` rows are extracted in a single enola run, so the graph also holds the edges between repositories: `reaches_route` from a client call to the route that serves it, cross-repository `calls`/`imports`.
• CLAUDE.md: enola writes the cluster snapshot into each member's `.enola-<dataset_id>` (enola's `output.dir`), not the `.enola` a single-repository run uses: a remote clone is shared by every dataset that adds its URL, and a cluster snapshot holds the other repositories' facts.
• CLAUDE.md: Deleting one (`forget(data_id=...)`, `datasets.delete_data`) does not run enola — the remaining rows are marked for re-extraction, and the next `cognify()` of the dataset rebuilds them, as after `forget(memory_only=True)`.
• CLAUDE.md: The enola run over a cluster gets the per-repository timeout times the member count, capped at `CLUSTER_ENOLA_TIMEOUT_CAP_SECONDS` (1 h).
• CLAUDE.md: `add_code_doc_edges` then writes a `describes` edge chunk → `CodeSymbol` (module docstring → `CodeModule`) by id through the graph engine, new edges only, and sweeps the documents/chunks (and their summaries) of the run's repositories that the run no longer produced, from the graph and …[+146 chars]
• CLAUDE.md: an unchanged re-run adds no node or edge, but `add_data_points` still re-stores and re-embeds every chunk it is handed.
• CLAUDE.md: `extract_entities=True` puts `cognify_code_doc_chunks` first: cognify's `extract_graph_and_summarize` (LLM) over the chunks, one `chunks_per_batch` slice at a time — the whole run reaches each task in one call (every task is a coroutine;
• CLAUDE.md: a streaming task would hand the sweep a piece of the run and it would delete the rest), so this slicing is what bounds the concurrent LLM requests.
• CLAUDE.md: | # | Mechanism | Question it answers | Stored where | Flag (default) | |---|---|---|---|---| | 1 | Source stamping | who/which run wrote this node | `source_*` fields on the graph node | `COGNEE_PROVENANCE_MODE` (`lightweight`) | | 2 | Graph source-refs | which documents own this node …[+604 chars]
• CLAUDE.md: Rows are ignored at read time when their pipeline run did not complete or their document is gone, and swept when a document is deleted or its memory dropped with `forget(memory_only=True)`.
• CLAUDE.md: A `cloud` origin sends only the events in `CLOUD_TELEMETRY_EVENTS` (`cognee/shared/utils.py`: run milestones and memory/search outcomes);
• CLAUDE.md: `Pipeline Run` events follow the dataset lifecycle in `run_tasks`;
• CLAUDE.md: completion is emitted only after durable storage and the run record succeed.
• CLAUDE.md: They carry `pipeline_event_scope=run`.
• CLAUDE.md: Historical item-scoped `Pipeline Run` events cannot establish whole-run completion;
• CLAUDE.md: Use `debugpy` optional dependency for debugging: `pip install cognee[debug]`

Hooks (1)

• .claude/settings.json (SessionStart): bash "$CLAUDE_PROJECT_DIR/.claude/hooks/link-skills.sh"

Git hooks (2)

• .pre-commit-config.yaml: pre-commit hooks from https://github.com/pre-commit/pre-commit-hooks at v3.2.0 (contributor tooling: runs only after pre-commit install) · uses the network
• .pre-commit-config.yaml: pre-commit hooks from https://github.com/astral-sh/ruff-pre-commit at v0.16.6 (contributor tooling: runs only after pre-commit install) · uses the network

Install scripts (8)

• cognee/modules/engine/operations/setup.py: python cognee/modules/engine/operations/setup.py
• cognee/tasks/graph/gliner_demo/install.py: python cognee/tasks/graph/gliner_demo/install.py
• examples/cookbooks/company_brain/company_qa/setup.py: python examples/cookbooks/company_brain/company_qa/setup.py
• examples/cookbooks/company_brain/follow_up_agent/setup.py: python examples/cookbooks/company_brain/follow_up_agent/setup.py
• examples/cookbooks/google_workspace_memory/setup.py: python examples/cookbooks/google_workspace_memory/setup.py
• examples/cookbooks/import_agent_sessions/setup.py: python examples/cookbooks/import_agent_sessions/setup.py
• examples/cookbooks/personalized_email/setup.py: python examples/cookbooks/personalized_email/setup.py
• examples/cookbooks/self_hosted_companion/setup.py: python examples/cookbooks/self_hosted_companion/setup.py