cognee 1.4.1.dev1__tar.gz → 1.5.0.dev1__tar.gz

cognee-1.5.0.dev1/.claude/skills/cognee-cli/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: cognee-cli
+description: Use when the user wants to drive cognee from the terminal with cognee-cli — remember/recall/forget/improve memory commands, managing datasets and config, 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
+
+The memory commands are the primary surface as of cognee 1.x:
+
+```bash
+cognee-cli remember "Your text here"         # also accepts file paths / URLs
+cognee-cli remember ./docs --dataset-name my_project
+cognee-cli recall "Your question"            # query the graph
+cognee-cli recall "keyword" --query-type CHUNKS
+cognee-cli forget --all                      # wipe local state
+```
+
+`remember` is ingest + graph build in one step (`add` + `cognify` under the
+hood); `--background`/`-b` runs the cognify stage in the background, and
+`--dry-run` estimates LLM tokens/cost without ingesting. `recall` takes
+`--datasets`/`-d`, `--top-k`/`-k` (default 10), and `--session-id`/`-s`.
+
+`forget` targets `--dataset`, `--dataset-id`, `--data-id` (needs a dataset), or
+`--everything`/`--all` — one unified command covering what `delete`, `prune`,
+and `empty_dataset` used to do separately.
+
+> **`forget --all` does not ask for confirmation.** It deletes every dataset
+> immediately, even on a non-interactive stdin. The legacy `delete --all`
+> prompts `Delete ALL data from cognee? [y/N]` first, so switching to `forget`
+> silently drops that safety net — script it with care.
+
+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.recall with `query_type=SearchType.TEMPORAL`
+
+Note the CLI defaults `--query-type` to `GRAPH_COMPLETION`, whereas the SDK's
+`cognee.recall()` auto-routes when `query_type` is omitted.
+
+## Session memory and enrichment
+
+Session entries are currently written from the SDK — `cognee.remember(...,
+session_id="chat_1")` — not the CLI (`cognee-cli remember` has no session
+flag). The CLI side of session memory is reading and bridging:
+
+```bash
+cognee-cli recall "question" -s chat_1       # session cache first: without -d/-t
+                                             # this searches the session directly
+cognee-cli sessions get                      # retrieve session Q&A history
+cognee-cli improve -d my_project -s chat_1   # bridge session content into the graph
+cognee-cli improve -d my_project             # enrich/index the graph (no session)
+cognee-cli feedback ...                      # attach feedback to results
+```
+
+`improve` also takes `--node-name`, `--feedback-alpha` (default 0.1), and
+`--background`/`-b`. `remember`/`improve` build their graphs through
+`cognify()`, so cognify-level settings (e.g. `CONTRADICTION_DETECTION=true`)
+apply to them too.
+
+## Legacy / lower-level commands
+
+`add`, `cognify`, `search`, `memify`, and `delete` still ship and are what the
+memory commands call underneath. Use them only to drive a single stage in
+isolation; prefer `remember`/`recall`/`forget`/`improve` otherwise.
+
+```bash
+cognee-cli add "text" && cognee-cli cognify  # what `remember` does in one step
+cognee-cli search "question"                 # `recall` minus routing/scope/session sources
+cognee-cli memify -d my_project              # custom extraction/enrichment tasks
+cognee-cli delete --all                      # superseded by `forget --all`
+```
+
+## 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
+```
+
+## 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.
+- `remember` (and `add`) without `--dataset-name` targets the default dataset
+  `main_dataset`; `recall`/`search` operate across your accessible datasets
+  unless a dataset is given.
+- `forget` refuses to run bare — pass `--dataset`, `--dataset-id`, `--data-id`
+  (with a dataset), or `--everything`/`--all`.
+- Session commands (`recall -s`, `sessions get`, `improve -s`) require
+  `CACHING=true` (the default) — with it off, session reads return nothing and
+  SDK session writes raise. To cut read latency and token cost while keeping
+  session memory, `cognee-cli config set AUTO_FEEDBACK false` — by default
+  cognee makes one structured-output LLM call per answered query to self-tune
+  its memory.
+- `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). `config reset` (reset
+  *all* keys) is still not implemented.
+- **Which `.env` actually wins is not always the cwd one.** At import, cognee
+  calls `dotenv.load_dotenv(override=True)`, which resolves relative to the
+  *cognee package location*, not your working directory. 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. Symptom: `config set` appears to do
+  nothing, or the CLI connects to a backend you thought you had overridden.
+  To test against different settings, move the repo `.env` aside, or set
+  values programmatically after import (`cognee.config.set_*`). (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. `-c`.)

cognee-1.5.0.dev1/.claude/skills/cognee-docker/SKILL.md

@@ -0,0 +1,88 @@
+---
+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
+# remember = ingest + build the graph in one call (multipart form)
+curl -X POST http://localhost:8000/api/v1/remember -F "data=@note.txt" -F "datasetName=main_dataset"
+# recall = query it (JSON)
+curl -X POST http://localhost:8000/api/v1/recall -H "Content-Type: application/json" \
+  -d '{"query": "What does Cognee do?", "datasets": ["main_dataset"]}'
+```
+
+`/api/v1/recall` takes the question as `query`. It defaults `search_type` to
+`GRAPH_COMPLETION` for backward compatibility — pass `"search_type": null` to
+opt into auto-routing (the SDK `recall()` default). The difference is real:
+`{"query": "Why does X?"}` answers with `GRAPH_COMPLETION`, while the same
+query with `"search_type": null` routes to `GRAPH_COMPLETION_COT`.
+
+Request DTOs accept both `snake_case` and `camelCase` for every field
+(`alias_generator=to_camel` + `populate_by_name` in `cognee/api/DTO.py`), so
+`search_type` and `searchType` are equally valid.
+
+The legacy `/api/v1/add` + `/api/v1/cognify` + `/api/v1/search` endpoints still
+exist and are what `remember`/`recall` call underneath; use them only when you
+need a single stage on its own. `/api/v1/improve` and `/api/v1/forget` complete
+the memory API.
+
+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.5.0.dev1/.claude/skills/cognee-install/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: cognee-install
+description: Use when the user wants to install cognee and run their first remember → recall 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
+
+As of cognee 1.x the memory API — `remember`, `recall`, `forget`, `improve` —
+is the primary surface. All SDK functions are async. Minimal end-to-end script:
+
+```python
+import asyncio
+import cognee
+
+async def main():
+    await cognee.remember("Cognee turns documents into AI memory.")
+    results = await cognee.recall("What does cognee do?")
+    print(results)
+
+asyncio.run(main())
+```
+
+`remember()` is the whole ingestion path in one call — it runs `add()` +
+`cognify()`, then `improve()` to index the graph (`self_improvement=True` by
+default). It accepts text, file paths, URLs, and binary streams, with an
+optional `dataset_name="my_project"`; pass `datasets=["my_project"]` to
+`recall()` to stay inside one dataset.
+
+`recall()` auto-routes the query to a search strategy by default. Pass
+`query_type=SearchType.CHUNKS` (etc.) to pin one, or `auto_route=False` to
+fall back to `GRAPH_COMPLETION`.
+
+Session memory is the other half of the API — `remember(..., session_id="chat_1")`
+writes to a fast session cache rather than running add+cognify inline, and
+`recall(..., session_id="chat_1")` reads it back (session hits short-circuit the
+graph search). With the default `self_improvement=True` it still bridges that
+data into the permanent graph in the background; `improve(dataset=...,
+session_ids=[...])` does the same explicitly. Session memory runs on the
+session cache, which is on by default (`CACHING=true`); setting
+`CACHING=false` disables it entirely and makes `remember(session_id=...)`
+raise.
+
+Start with `examples/demos/remember_recall_improve_example.py`, which walks
+through permanent memory, session memory, and the sync between them.
+
+The `add()` / `cognify()` / `search()` / `memify()` primitives still exist and
+are what `remember`/`recall`/`improve` call underneath — reach for them when you
+need to drive a stage in isolation (e.g. custom pipeline tasks), not for
+ordinary ingestion. `cognee.delete` is formally deprecated (since 0.3.9);
+`forget()` is the v1 replacement, unifying the old delete/prune/empty_dataset
+paths behind one call. When to use `recall()` versus the low-level `search()`
+is covered in `docs/recall-vs-search.md`.
+
+## Verify / troubleshoot
+
+- `cognee-cli remember "hello" && cognee-cli recall "hello"` exercises the same
+  flow from the shell.
+- To wipe local state during experiments: `cognee-cli forget --all` (or
+  `await cognee.forget(everything=True)`).
+- Reads slow or spending tokens on every query → set `AUTO_FEEDBACK=false`
+  (keep `CACHING=true`); by default cognee makes one structured-output LLM
+  call per answered query to self-tune its memory.
+- Structured LLM output errors usually mean the model/provider needs an
+  explicit instructor mode: `LLM_INSTRUCTOR_MODE="json_schema_mode"`.

cognee-1.5.0.dev1/.claude/skills/cognee-integrations/SKILL.md

@@ -0,0 +1,73 @@
+---
+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 forget --all` or
+`await cognee.forget(everything=True)`) and re-ingest with `remember()`.
+
+To drop just the graph and vectors while keeping the ingested files, use
+`await cognee.forget(dataset="my_project", memory_only=True)` — the dataset can
+then be rebuilt under the new embedding model without re-uploading anything.

cognee-1.5.0.dev1/.claude/skills/cognee-permissions/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: cognee-permissions
+description: Use when working with cognee's permission system — understanding or changing how users, roles, and tenants get access to datasets, how ACL grants work, where permissions are enforced in add/cognify/search/delete, and how the grant records surface in the memory-provenance view.
+---
+
+# The cognee permission system
+
+## The master switch
+
+`ENABLE_BACKEND_ACCESS_CONTROL` decides whether any of this runs:
+
+- `true` (default): multi-tenant mode. Every API call requires auth, every
+  dataset operation is permission-checked, and each user+dataset pair gets
+  isolated graph/vector/relational databases (tracked in the
+  `DatasetDatabase` model, supported backends: Kuzu, LanceDB, SQLite,
+  Postgres).
+- `false`: single-user mode. Permission checks short-circuit to allowed,
+  there is no per-dataset isolation, and **every user's operations resolve
+  to the same shared databases and datasets**. Authentication is a separate
+  knob: `REQUIRE_AUTHENTICATION`. Unset, it inherits this switch (so
+  turning access control off also turns auth off) — but if
+  `REQUIRE_AUTHENTICATION=true` is set, endpoints still demand a login;
+  authenticated users are identified but *not isolated*, all pointing at
+  the same data. The reverse misconfiguration
+  (`REQUIRE_AUTHENTICATION=false` with access control on) is ignored: auth
+  is forced on with a warning, because multi-tenant isolation is
+  meaningless without identity (`get_authenticated_user.py`).
+
+## The core model: principals, permissions, ACL grants
+
+Everything reduces to one relation — **a grant**: *principal* × *permission*
+× *dataset*, stored as one `ACL` row (`modules/users/models/ACL.py`).
+
+- **Principal** (`Principal.py`) is polymorphic: `User`, `Role`, and
+  `Tenant` all inherit from it. Any of the three can hold a grant, which is
+  how role-wide and tenant-wide access work — one ACL row covers every
+  member.
+- **Permission** (`Permission.py`) is one of exactly four names, defined in
+  `permissions/permission_types.py`: `read`, `write`, `delete`, `share`.
+  `share` is the meta-permission: it gates granting/revoking access for
+  others.
+- **Membership** is separate from grants: `UserRole` and `UserTenant` link
+  users into roles/tenants. A user's effective access is the union of their
+  own grants and the grants of every role/tenant they belong to.
+
+## How grants come into existence
+
+1. **Dataset creation** (`modules/data/methods/create_authorized_dataset.py`):
+   the creating user is granted **all four permissions** on the new dataset.
+   If the user has a `parent_user_id` (sub-users/agent identities), the
+   parent is auto-granted all four as well — parents always see their
+   children's datasets.
+2. **Explicit sharing** (`permissions/methods/
+   authorized_give_permission_on_datasets.py`): the caller must hold
+   `share` on the target datasets, then any principal (user, role, or
+   tenant) can be granted any permission. Revocation mirrors this
+   (`authorized_revoke_permission_on_datasets.py`).
+3. **Capabilities — tenant-scoped grants of actions, not data** (landing
+   via PR #4302, currently in review): a new `principal_capabilities`
+   table, keyed on `(principal, tenant, capability)`. Where an ACL row
+   grants access to *a dataset*, a capability grants *an action inside a
+   tenant* — the first one being `manage_users`. The catalog of capability
+   names is code (`CAPABILITY_TYPES` in `permission_types.py`), not a
+   database table, "because the code is what gives each name meaning";
+   only the assignment of a capability to a principal is data. `tenant_id`
+   is stored on every row because a user can belong to multiple tenants:
+   it pins each grant to the user's membership in one specific tenant, so
+   holding a capability in one tenant never carries over to the same
+   user's other tenants. Resolution
+   (`get_effective_capabilities(user, tenant)`) returns the union of what
+   the tenant grants all of its members, what the user's roles in that
+   tenant grant, and what the user was granted personally — there is no
+   deny in the model, resolution is gated on actual tenant membership, and
+   the tenant owner short-circuits as holding every capability.
+   Grant/revoke endpoints ride the permissions router.
+
+## Where permissions are enforced
+
+The single chokepoint for dataset resolution is
+`get_authorized_existing_datasets(datasets, permission, user)` — every
+entrypoint resolves names/IDs through it with the permission it needs:
+
+| Operation | Required permission | Enforcement path |
+|---|---|---|
+| `add` / `cognify` / `remember` | `write` | dataset resolution before the pipeline runs |
+| `search` / `recall` / visualize | `read` | dataset resolution; retrieval is restricted to documents of readable datasets |
+| `delete` / prune of a dataset | `delete` | `datasets.py` resolves with `"delete"` |
+| grant/revoke for others | `share` | `authorized_give/revoke_permission_on_datasets` |
+
+Two behaviors worth knowing:
+
+- **Denied reads return empty results, not 403.** A search against a
+  dataset you cannot read yields `[]` — deliberate, to avoid leaking which
+  datasets exist. When debugging "search returns nothing", check grants
+  before checking the graph.
+
+## Roles, tenants, and who may manage them
+
+- **User management** (listing tenant users, assigning/removing roles,
+  adding/removing users) is allowed for the **tenant owner** always, and
+  today for members of roles named in `USER_MANAGEMENT_ALLOWED_ROLE_NAMES`
+  (currently `{"admin"}`, `permissions/permission_types.py`). That
+  name-matching is a known footgun — any customer group that happens to be
+  called "admin" gets user management — and PR #4302 replaces it: the
+  check becomes "does the requester hold the `manage_users` capability in
+  this tenant" (owner always passes), with the role-name match kept only
+  as a deprecated fallback so tenants upgrading from the old check don't
+  lose user management until their `admin` role is granted the capability.
+- **Role visibility**: members of a role can see the role itself and their
+  co-members; anyone with user-management permission sees all
+  (`tenants/methods/get_users_in_role.py`). Lookups are tenant-scoped — a
+  role id from another tenant cannot be used to read that tenant's members.
+
+## The grant records in memory provenance (the new grant view)
+
+`api/v1/visualize/memory_provenance.py` surfaces the ACL grants as
+first-class graph data. Each grant becomes an `AclGrantRecord`:
+
+```python
+{"principal_id": ..., "principal_kind": "user" | "role" | "tenant", "permission": ...}
+```
+
+and is rendered into the provenance graph as an edge from the principal
+node to the dataset, with the permission mapped to a relation name
+(`_ACL_EDGE_RELATIONS`):
+
+| permission | provenance edge |
+|---|---|
+| read | `reads` |
+| write | `writes` |
+| delete | `can_delete` |
+| share | `can_share` |
+
+Grants are rendered (never dropped) even when the principal is unknown,
+because "an ACL row exists because someone granted it". The view is exposed
+through the schema router (`get_schema_router.py`):
+`visualize_memory_provenance` (HTML) and `get_memory_provenance_payload`
+(JSON) — this is where you *see* the permission state of a memory rather
+than query it.
+
+## HTTP API surface (`api/v1/permissions/routers/get_permissions_router.py`)
+
+| Endpoint | What it does |
+|---|---|
+| `POST /permissions/datasets/{principal_id}` | grant a permission on datasets to a principal (requires `share`) |
+| `DELETE /permissions/datasets/{principal_id}` | revoke a permission |
+| `POST /permissions/roles` · `DELETE /permissions/roles/{role_id}` | create/delete a role |
+| `POST/DELETE /permissions/users/{user_id}/roles` | add/remove a user to/from a role |
+| `POST /permissions/users/{user_id}/tenants` | add a user to a tenant |
+| `GET /permissions/tenants/{tenant_id}/roles/{role_id}/users` | members of a role (self-visible to members) |
+| `GET /permissions/tenants/{tenant_id}/roles/users/{user_id}` | a user's roles |
+| `GET /permissions/tenants/{tenant_id}/users` | users in a tenant |
+| `GET /permissions/tenants/me` | the caller's tenants |
+
+## Key files map
+
+- Models: `cognee/modules/users/models/` — `ACL`, `Principal`, `Permission`,
+  `Role`, `Tenant`, `UserRole`, `UserTenant`, `DatasetDatabase` (and
+  `PrincipalCapability` once #4302 lands)
+- Methods: `cognee/modules/users/permissions/methods/` — grant/revoke,
+  checks, dataset resolution, document filtering
+- Enforcement chokepoint: `cognee/modules/data/methods/`
+  (`get_authorized_existing_datasets`, `create_authorized_dataset`)
+- Grant provenance view: `cognee/api/v1/visualize/memory_provenance.py`
+- HTTP API: `cognee/api/v1/permissions/routers/get_permissions_router.py`

cognee-1.5.0.dev1/.claude/skills/cognee-server/SKILL.md

@@ -0,0 +1,71 @@
+---
+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/` — the memory API is `remember`
+  (plus `remember/entry`), `recall`, `improve`, `forget`; `sessions` covers
+  session memory; `datasets`, `users`, `visualize` handle the rest. The legacy
+  `add`, `cognify`, `search`, `memify`, and `delete` routes still exist and are
+  what the memory routes call underneath (see `cognee/api/client.py` for the
+  registered routers, or `GET /openapi.json` on a running server).
+
+  Note there is **no `/api/v1/feedback` route** — `feedback` exists as a CLI
+  command and in the SDK, but is not exposed over HTTP.
+
+## 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.
+- `recall`/`search` returns `[]` instead of erroring → permission-filtered
+  result; check dataset access rights for the calling user.