cognee 1.4.0.dev4__tar.gz → 1.4.0.dev20260803__tar.gz

cognee-1.4.0.dev20260803/.claude/skills/cognee-cli/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: cognee-cli
+description: Use when the user wants to drive cognee from the terminal with cognee-cli — ingesting data, building and searching the knowledge graph, managing datasets and config, memory commands, or database migrations.
+---
+
+# Use the cognee CLI
+
+`cognee-cli` ships with the package (entry point in `cognee/cli/_cognee.py`;
+each command lives in `cognee/cli/commands/`). Every command has
+`--help` with examples — prefer that over guessing flags. Needs
+`LLM_API_KEY` configured, same as the SDK.
+
+## Core flow
+
+```bash
+cognee-cli add "Your text here"              # also accepts file paths / URLs
+cognee-cli add ./docs --dataset-name my_project
+cognee-cli cognify                           # build the knowledge graph
+cognee-cli search "Your question"            # GRAPH_COMPLETION by default
+cognee-cli search "keyword" --query-type CHUNKS
+cognee-cli delete --all                      # wipe local state
+```
+
+Search types match exactly 7 of the SDK's `SearchType` enum (`cognee/modules/search/types/SearchType.py`), those 7 being chosen in (`cognee/cli/config.py:SEARCH_TYPE_CHOICES`):
+GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS, SUMMARIES, CODE, CYPHER, GRAPH_REPORT
+Others must be reached from the SDK, not CLI; e.g. call cognee.search with `query_type=SearchType.TEMPORAL`
+
+## Management
+
+```bash
+cognee-cli datasets list                     # dataset operations
+cognee-cli config get [key] [--show-secrets] # view one/all settings (API keys masked by default)
+cognee-cli config set <key> <value>          # set + persist to ./.env in the cwd
+cognee-cli config unset <key>                # reset a key to its default (also persisted)
+cognee-cli -ui                               # launch API server + UI (see cognee-server skill)
+cognee-cli serve --url http://localhost:8000 # connect CLI/SDK to a running instance
+```
+
+## Memory commands
+
+Higher-level agent-memory surface on top of the core flow:
+
+```bash
+cognee-cli remember "fact to keep"           # store into permanent memory
+cognee-cli recall "what do I know about X"   # retrieve
+cognee-cli memify                            # enrich the graph
+cognee-cli forget ...                        # remove memories
+cognee-cli improve                           # bridge session memory into the graph
+cognee-cli sessions get                      # retrieve session Q&A history
+cognee-cli feedback ...                      # attach feedback to results
+```
+
+`remember`/`improve` build their graphs through `cognify()`, so cognify-level
+settings (e.g. `CONTRADICTION_DETECTION=true`) apply to them too.
+
+## Relational DB migrations (Alembic)
+
+```bash
+cognee-cli upgrade        # apply migrations
+cognee-cli downgrade
+cognee-cli history
+cognee-cli current
+```
+
+Typically needed after version upgrades when the server refuses to start on
+an old schema.
+
+## Gotchas
+
+- The CLI initializes cognee lazily; the first command in a fresh environment
+  is slow (DB + model setup), later ones are fast.
+- `add` without `--dataset-name` targets the default dataset `main_dataset`;
+  cognify/search operate across your accessible datasets unless a dataset is
+  given.
+- `memify` requires one of the arguments -d/--dataset-name --dataset-id
+- `config set`/`config unset` write to the `.env` file in whatever directory
+  you run the command from (creating it if missing) — run later
+  `cognee-cli`/SDK commands from that same directory to see the change take
+  effect, same as editing `.env` by hand. `config reset` (reset *all* keys)
+  is still not implemented.

cognee-1.4.0.dev20260803/.claude/skills/cognee-docker/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: cognee-docker
+description: Use when the user wants to run cognee with Docker or docker compose — trying it out from the prebuilt image, starting the API server in a container, or bringing up the full stack (UI, MCP, Postgres, Neo4j) with compose profiles.
+---
+
+# Start cognee from the Docker image
+
+## Fastest path: prebuilt image, one file
+
+For a local try-out, do NOT clone or build anything. Follow
+`docs/minimal-docker-compose.md`: save this as `docker-compose.yml` in an
+empty directory:
+
+```yaml
+services:
+  cognee:
+    image: cognee/cognee:main
+    ports:
+      - "8000:8000"
+    environment:
+      LLM_API_KEY: ${LLM_API_KEY:?set LLM_API_KEY to your OpenAI API key}
+      # Single-user try-out: no auth, shared local databases.
+      ENABLE_BACKEND_ACCESS_CONTROL: "false"
+```
+
+Then:
+
+```bash
+export LLM_API_KEY="sk-..."   # OpenAI key (default LLM + embedding provider)
+docker compose up
+curl http://localhost:8000/health
+```
+
+Interactive API reference: http://localhost:8000/docs. First requests:
+
+```bash
+echo "Cognee turns documents into AI memory." > note.txt
+curl -X POST http://localhost:8000/api/v1/add -F "data=@note.txt" -F "datasetName=main_dataset"
+curl -X POST http://localhost:8000/api/v1/cognify -H "Content-Type: application/json" -d '{"datasets": ["main_dataset"]}'
+curl -X POST http://localhost:8000/api/v1/search -H "Content-Type: application/json" -d '{"searchType": "GRAPH_COMPLETION", "query": "What does Cognee do?", "datasets": ["main_dataset"]}'
+```
+
+Data lives inside the container by default. To persist it, set
+`DATA_ROOT_DIRECTORY=/cognee-data/data` and
+`SYSTEM_ROOT_DIRECTORY=/cognee-data/system` and mount a named volume at
+`/cognee-data` (full example in `docs/minimal-docker-compose.md`).
+
+## Full stack from the repo
+
+The repository's `docker-compose.yml` builds from source and adds opt-in
+profiles. From the repo root (needs a `.env` with at least `LLM_API_KEY`;
+copy `.env.template`):
+
+```bash
+docker compose up                                  # API server only, port 8000
+docker compose --profile ui up                     # + frontend on port 3000
+docker compose --profile mcp up                    # + MCP server on port 8001
+docker compose --profile postgres --profile neo4j up   # + databases
+```
+
+Postgres profile: pgvector/pg17, user/password/db `cognee`/`cognee`/`cognee_db`
+on 5432. Neo4j profile: `neo4j`/`pleaseletmein` on 7474/7687. When cognee runs
+in a container and the database on the host, use `DB_HOST=host.docker.internal`.
+
+## Gotchas
+
+- With `ENABLE_BACKEND_ACCESS_CONTROL` unset (defaults to true), every API
+  call requires authentication — the single-user try-out sets it to `false`.
+- The image defaults to OpenAI for both LLM and embeddings; configuring only
+  one of them leaves the other on OpenAI, so keep a valid OpenAI key or
+  configure both (see the cognee-integrations skill).

cognee-1.4.0.dev20260803/.claude/skills/cognee-install/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: cognee-install
+description: Use when the user wants to install cognee and run their first add → cognify → search flow with the Python SDK — fresh setup, virtual env, extras selection, or a minimal working example.
+---
+
+# Install and run cognee
+
+## Install
+
+Requires Python 3.10–3.14. Prefer uv:
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install cognee            # from PyPI
+# or, working inside this repo:
+uv pip install -e .
+```
+
+Add extras only when needed — examples: `cognee[postgres]`, `cognee[neo4j]`,
+`cognee[docling]` (office/HTML document parsing, slim), `cognee[docs]`
+(unstructured), `cognee[anthropic]`, `cognee[ollama]`, `cognee[aws]`. The full
+list is in `pyproject.toml` under `[project.optional-dependencies]`.
+
+## Configure
+
+The only required setting is an LLM API key. Create `.env` in the working
+directory (or export the variable):
+
+```bash
+LLM_API_KEY="your_openai_api_key"
+```
+
+Defaults need no services: SQLite (relational), LanceDB (vector), and Ladybug
+(graph), all stored locally. OpenAI is the default LLM and embedding provider —
+if you configure a different LLM but not embeddings (or vice versa), the other
+silently stays on OpenAI. For other providers and databases use the
+cognee-integrations skill.
+
+## First run
+
+All SDK functions are async. Minimal end-to-end script:
+
+```python
+import asyncio
+import cognee
+
+async def main():
+    await cognee.add("Cognee turns documents into AI memory.")
+    await cognee.cognify()
+    results = await cognee.search("What does cognee do?")
+    print(results)
+
+asyncio.run(main())
+```
+
+`add()` accepts text, file paths, and URLs, with an optional
+`dataset_name="my_project"`; pass `datasets=["my_project"]` to `cognify()` and
+`search()` to stay inside one dataset. More runnable examples live in
+`examples/` (start with `examples/demos/simple_cognee_example.py`).
+
+## Verify / troubleshoot
+
+- `cognee-cli add "hello" && cognee-cli cognify && cognee-cli search "hello"`
+  exercises the same flow from the shell.
+- To wipe local state during experiments: `cognee-cli delete --all`.
+- Structured LLM output errors usually mean the model/provider needs an
+  explicit instructor mode: `LLM_INSTRUCTOR_MODE="json_schema_mode"`.

cognee-1.4.0.dev20260803/.claude/skills/cognee-integrations/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cognee-integrations
+description: Use when the user wants to connect cognee to external services — switching LLM or embedding providers (OpenAI, Azure, Gemini, Anthropic, Ollama, OpenRouter), changing databases (Postgres, PGVector, Neo4j, Neptune, Turso), S3 storage, or the MCP server for IDE integration.
+---
+
+# Set up cognee integrations
+
+All integration config is environment variables (`.env`). The authoritative,
+always-current list with commented examples is `.env.template` at the repo
+root — check it before inventing variable names. Install the matching extra
+before switching a backend (e.g. `pip install cognee[postgres]`).
+
+## LLM providers
+
+Default is OpenAI (`LLM_API_KEY` is all you need). To switch, set
+`LLM_PROVIDER`, `LLM_MODEL`, `LLM_API_KEY`, and (where relevant)
+`LLM_ENDPOINT` / `LLM_API_VERSION`:
+
+- **Azure OpenAI**: `LLM_PROVIDER=azure`, `LLM_MODEL=azure/gpt-4o-mini`, endpoint + api version required.
+- **Gemini** (no extra needed): `LLM_PROVIDER=gemini`, `LLM_MODEL=gemini/gemini-2.0-flash-exp`.
+- **Anthropic** (`cognee[anthropic]`): `LLM_PROVIDER=anthropic`, model e.g. `claude-3-5-sonnet-20241022`.
+- **Ollama, local** (`cognee[ollama]`): `LLM_PROVIDER=ollama`, `LLM_ENDPOINT=http://localhost:11434/v1`, and set the embedding block + `HUGGINGFACE_TOKENIZER` too.
+- **Custom / OpenRouter / vLLM**: `LLM_PROVIDER=custom` with the provider's OpenAI-compatible endpoint.
+- **AWS Bedrock** (`cognee[aws]`): `LLM_PROVIDER=bedrock` + AWS credentials/region.
+
+**The classic trap**: LLM and embeddings are configured independently
+(`EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, `EMBEDDING_ENDPOINT`,
+`EMBEDDING_API_KEY`). Configuring only one leaves the other on OpenAI —
+either keep a valid OpenAI key or configure both.
+
+## Databases
+
+- **Relational** (`DB_PROVIDER`): sqlite (default) or postgres
+  (`cognee[postgres]`; host/port/user/password/name via `DB_*` vars).
+- **Vector** (`VECTOR_DB_PROVIDER`): lancedb (default), pgvector
+  (`cognee[postgres]`, needs `VECTOR_DB_URL`), neptune_analytics
+  (`cognee[neptune]`), turso (`cognee[turso]`). 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; setting `VECTOR_DB_PROVIDER` alone raises
+  "Unsupported vector database provider".
+- **Graph** (`GRAPH_DATABASE_PROVIDER`): ladybug (default), neo4j
+  (`cognee[neo4j]`, bolt URL + credentials), neptune (`cognee[neptune]`),
+  ladybug-remote, postgres (no raw Cypher / natural-language search).
+
+The repo `docker-compose.yml` ships ready-to-use `postgres` (pgvector) and
+`neo4j` profiles with matching default credentials. From a container, reach
+host services with `DB_HOST=host.docker.internal`.
+
+## Storage, cache, and the rest
+
+- **S3 storage** (`cognee[aws]`): `STORAGE_BACKEND=s3` + bucket/credentials,
+  and point `DATA_ROOT_DIRECTORY`/`SYSTEM_ROOT_DIRECTORY` at `s3://` paths.
+- **Session cache**: `CACHE_BACKEND` = sqlite (default) | postgres | redis | fs | tapes.
+- **Ontologies**: `ONTOLOGY_FILE_PATH` to an OWL file, resolver/matching via
+  `ONTOLOGY_RESOLVER` / `MATCHING_STRATEGY`.
+
+## MCP server (IDE integration)
+
+`docker compose --profile mcp up` starts the MCP server on port 8001
+(SSE transport), built from `cognee-mcp/`. Point Cursor / Claude Desktop /
+Claude Code at it to use cognee memory from the IDE. Configure its `DB_*` env
+to match the main service so both see the same data.
+
+## After changing providers mid-project
+
+Embeddings from different models are not comparable — after switching the
+embedding provider or model, reset local state (`cognee-cli delete --all` or
+`cognee.prune`) and re-cognify.

cognee-1.4.0.dev20260803/.claude/skills/cognee-server/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cognee-server
+description: Use when the user wants to run the cognee API server (and optional UI) on their own machine — starting it, checking it's healthy, connecting the SDK or other clients to it, and choosing the right auth posture.
+---
+
+# Start the cognee server locally
+
+## From an installed cognee (no Docker)
+
+```bash
+cognee-cli -ui
+```
+
+launches the full local stack: FastAPI backend on **http://localhost:8000**
+and the UI on **http://localhost:3000**. Needs `LLM_API_KEY` in the
+environment or `.env`. The interactive API reference is at
+http://localhost:8000/docs, health at `/health`.
+
+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).
+
+## Auth posture
+
+`ENABLE_BACKEND_ACCESS_CONTROL` decides everything:
+
+- `true` (default): multi-tenant — auth required on every API call, per
+  user+dataset database isolation.
+- `false`: single-user local mode — no auth, shared local databases. Right
+  choice for a personal dev server; never for anything exposed.
+
+`REQUIRE_AUTHENTICATION=false` is ignored while access control is on; to turn
+auth off you must set `ENABLE_BACKEND_ACCESS_CONTROL=false`.
+
+## Connecting clients to the running server
+
+- **SDK / CLI against the server** (instead of embedded local mode):
+
+  ```bash
+  cognee-cli serve --url http://localhost:8000        # local instance
+  cognee-cli serve                                    # cognee cloud (device flow)
+  cognee-cli serve --logout                           # disconnect
+  ```
+
+  In Python: `await cognee.serve(url="http://localhost:8000")`.
+
+- **HTTP**: main routes live under `/api/v1/` — `add`, `cognify`, `search`,
+  `memify`, `datasets`, `users`, `visualize` (see `cognee/api/v1/`).
+
+## Graph visualization without the full UI
+
+```python
+from cognee.api.v1.visualize import visualization_server
+
+shutdown = visualization_server(port=8080)  # synchronous; returns a shutdown callable
+```
+
+## Troubleshooting
+
+- Port 8000 already taken → stop the other service or remap (compose:
+  `"8080:8000"`).
+- 401/403 on every call → you're in multi-tenant mode; either authenticate or
+  set `ENABLE_BACKEND_ACCESS_CONTROL=false` and restart.
+- Search returns `[]` instead of erroring → permission-filtered result;
+  check dataset access rights for the calling user.