cognee 1.5.0.dev2__tar.gz → 1.5.0.dev3__tar.gz

cognee-1.5.0.dev3/.claude/skills/cognee-community/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cognee-community
+description: Use when the user needs something that ships outside cognee core — community database adapters (Qdrant, Milvus, Weaviate, Redis, Pinecone, FalkorDB, Memgraph, DuckDB, NetworkX, …), data-source connectors (Slack, Gmail, Notion, Confluence, Google Drive), custom tasks/pipelines/retrievers (Exa, ScrapeGraph, codify), Keywords AI observability — or wants to contribute a package to the cognee-community repo.
+---
+
+# Use and contribute cognee-community packages
+
+Community-maintained plugins live in a separate monorepo:
+https://github.com/topoteretes/cognee-community. Everything installable is
+under `packages/`; `experimental/` holds demos (n8n nodes, dlt demos,
+bauplan, tower) that are not published packages. Each package publishes to
+PyPI as `cognee-community-<family>-<kind>-<name>` and imports as the same
+name with underscores.
+
+## Package families
+
+| Family | Packages |
+|---|---|
+| Vector adapters | azureaisearch, milvus, moss, opengauss, opensearch, pinecone, qdrant, redis, singlestore, turbopuffer, valkey, weaviate |
+| Graph adapters | arcadedb, memgraph, networkx, pggraph, spanner, turbopuffer, turingdb |
+| Hybrid (graph+vector in one DB) | arcadedb, duckdb, falkordb, helixdb |
+| Connectors (data sources) | confluence, gmail, google-drive, notion, slack |
+| Tasks / pipelines / retrievers | codify_tasks, codify_pipeline, code_retriever, exa_tasks, scrapegraph_tasks |
+| Observability | keywordsai (`MONITORING_TOOL=keywordsai` + `KEYWORDSAI_API_KEY`) |
+
+## Using a database adapter
+
+Install, then **import the package's `register` module before cognee touches
+any engine** — registration is what makes the provider name valid:
+
+```python
+uv pip install cognee-community-vector-adapter-qdrant
+```
+
+```python
+import cognee
+from cognee import config
+from cognee_community_vector_adapter_qdrant import register  # noqa: F401
+
+config.set_vector_db_config({
+    "vector_db_provider": "qdrant",
+    "vector_db_url": "http://localhost:6333",
+    "vector_db_key": "...",
+    "vector_dataset_database_handler": "qdrant",  # only if the adapter ships one
+})
+```
+
+The `register.py` calls `use_vector_adapter(name, AdapterClass)` /
+`use_graph_adapter(...)`. Setting `VECTOR_DB_PROVIDER`/`GRAPH_DATABASE_PROVIDER`
+to a community name **without** the register import raises "Unsupported
+vector database provider". Hybrid adapters (e.g. falkordb) register as both
+graph and vector — set both configs to the same provider name.
+
+**Multi-tenancy caveat**: with `ENABLE_BACKEND_ACCESS_CONTROL=true` (the
+default), both backends must have a dataset-database handler or cognee raises
+`EnvironmentError`. Community adapters that ship one (registered via
+`use_dataset_database_handler` in their `register.py`): qdrant, moss,
+singlestore, turbopuffer (vector + graph), falkordb, arcadedb, helixdb. All
+other community adapters need `ENABLE_BACKEND_ACCESS_CONTROL=false`.
+
+## Using a connector
+
+Connectors expose a `dlt` source you hand straight to `remember()`; they
+reuse core's DLT ingestion path, so snapshot sync and forget-on-delete work
+with no core changes:
+
+```python
+from cognee_community_connector_slack import slack_export_source
+
+await cognee.remember(
+    slack_export_source("/path/to/slack-export"),
+    dataset_name="team-slack-export",  # use a dedicated dataset
+    max_rows_per_table=0,
+)
+```
+
+Same shape for gmail ("ask my inbox"), notion, confluence, and google-drive
+(incremental, forget-on-delete). Each package README documents its
+credentials; always give a connector its own dataset.
+
+## Verifying an install
+
+Every package has `examples/example.py` (run `uv run python examples/example.py`
+from the package dir) and a `tests/` directory. An LLM API key is still
+required (`LLM_API_KEY`, OpenAI by default).
+
+## Contributing a package
+
+- **Branch from `main`** — unlike the core repo, cognee-community does not
+  use a `dev` branch.
+- 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.
+- 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).
+- Add a handler via `use_dataset_database_handler(...)` if the backend can
+  isolate per user+dataset — that's what makes it work with access control on.
+- Name it `cognee-community-<family>-<kind>-<name>` and add it to the tables
+  in the repo README. Lint config is the repo-root `ruff.toml`.

cognee-1.5.0.dev3/.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/advanced_guides/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"`.