Before You Start
- Complete Quickstart to understand basic operations
- Read Pipelines and Tasks for how a custom pipeline is assembled from tasks
- Set
CODE_GRAPH_REPO_PATHto the repository you want to index — it defaults to the current working directory - No LLM Providers or embedding configuration is required: both the pipeline and
SearchType.CODEare deterministic. The optional docstring pipeline is the exception: it embeds what it stores, so it needs an embedding provider - Optionally, set
CODE_GRAPH_DOCS=1to also store the repository’s docstrings as searchable chunks — this step embeds them, so it needs an embedding provider configured (still no LLM key)
Code in Action
What Just Happened
Step 1: Choose the Repository and Start Clean
CODE_GRAPH_REPO_PATH, falling back to the directory you run the script from. Pruning first means the graph you inspect afterwards contains only what this run extracted.
Step 2: Run the Code Graph Pipeline
get_code_graph_tasks() returns the three ordered tasks the pipeline runs: extract (run enola over the repository and map its facts to DataPoints), load the graph nodes, then load the typed relations as edges. Because nothing here calls an LLM or an embedding model, skip_connection_test=True skips the first-run provider checks so the pipeline runs without any API key.
Step 3: Query the Graph with SearchType.CODE
SearchType.CODE is driven by the structured code_query argument rather than by query_text, which stays empty here. The query_facts operation filters the extracted facts — by kinds in this case — and returns the first limit matches, so the result is a deterministic listing rather than a similarity ranking.
Step 4: Draw the Architecture and Read the Insights
architecture operation rolls symbol-level edges up to the modules that declare them and returns a ready-to-render diagram alongside the nodes — Mermaid by default, Graphviz with "diagram": "dot". The insights operation returns the findings enola’s explainers produced over the same graph, each with the evidence facts behind it; min_confidence separates the structural findings that always score 1.0 from the heuristic ones below it.
Step 5: Store Docstrings as Searchable Chunks (Optional)
CODE_GRAPH_DOCS set, cognify_code_docs_pipeline() reads the code graph built above and stores each documented symbol’s docstring as a DocumentChunk whose text starts with its file:line and signature, linked to its CodeSymbol by a describes edge. Retrievers that search chunks, such as SearchType.CHUNKS, can then answer “what does X do” from the docstring, and in the graph the describes edge leads from that chunk to the symbol in one hop. The step only embeds the chunks, so it needs an embedding provider but no LLM; passing extract_entities=True would add cognify’s LLM entity extraction and summaries over the chunks.
Step 6: Reuse the Same Shape for Other Operations
cognee.search() call with a different code_query. Take a fact id from the query_facts output above and feed it to explore to see a fact’s neighborhood, traverse to walk edges in one direction, find_path to connect two facts, or impact_analysis to see what depends on a fact. query_facts also filters on a fact property with prop and prop_value; the dependency example above lists the packages declared in the repository’s manifests. There is also a delta operation, which needs no fact id: code_query={"operation": "delta"} reports what the last ingestion changed in each repository.
When you don’t have a fact id yet, start from the navigation operations. search ranks symbols, routes, flows and modules against free text (BM25 over names, docstrings and file paths). hubs lists the most connected symbols, neighbors lists every edge of one node, and subgraph returns a bounded graph around up to 20 seeds. flows lists the program’s entry points and what their calls reach. ask takes a plain-language question and returns matching seeds, the flows through them, their one-hop neighbourhood and file:line citations to read; no model writes any of it. capabilities reports whether the graph has docstrings and flows, its node, symbol and flow counts, and every operation’s limits. Test code is left out of search, hubs and ask unless you pass "include_tests": true. Every operation’s full argument list, defaults, and the fact kinds a query can filter on are in the SearchType reference.
Advanced Usage
Make the Facts Available to Semantic Retrievers
Make the Facts Available to Semantic Retrievers
get_code_graph_tasks(repo_path, index_vectors=True) also writes the extracted facts to the vector store, so semantic and LLM-backed retrievers can reach them. It is opt-in because SearchType.CODE reads the graph only; enabling it adds embedding calls and therefore needs an embedding provider configured.Query from an MCP Client
Query from an MCP Client
The Cognee MCP server exposes the same operations to agents:
code_search takes the operation and its code_query fields as arguments, and recall accepts code in scope with a code_query to combine a code-graph query with other memory sources in one call.Docstrings and Flows
Docstrings and Flows
When enola records a symbol’s doc comment, it becomes the node’s
doc field and its description, so search and ask match on it.Each flow in enola’s flows.json becomes a CodeFlow node, linked to its entry symbol by flow_entry, to its stages by flow_stage, and to the routes it serves by flow_route. flows.json is only read when the snapshot’s receipt.json says this run wrote it (a snapshot without a receipt reads it as is): an enola run without the flows renderer leaves an earlier run’s file in place, and those flows would describe other code. A snapshot without docstrings or flows ingests as before, and the flows operation then raises a feature_unavailable error saying the graph has no flows. Flows that share a name in one repository, such as two services serving GET /health, are named after their entry as well, for example GET /health (svc_a/app.health), so they stay separate nodes.A repository whose code did not change is still mapped again on its next ingestion when cognee’s fact-to-graph mapping has changed since it was last indexed, so an existing graph picks up docstrings and flows without a code change.The doc field holds only the first paragraph of a doc comment. To store full docstrings where recall() and the chunk and completion search types can find them, see Store Docstrings as Searchable Memory below.Store Docstrings as Searchable Memory
Store Docstrings as Searchable Memory
SearchType.CODE is the only search type that reads code nodes, so by default recall(), CHUNKS, GRAPH_COMPLETION and HYBRID_COMPLETION cannot answer “what does X do” about your code. cognify_code_docs_pipeline closes that gap. It reads the docstrings of every repository whose code graph is already in the dataset and stores them as ordinary document chunks, which every chunk-based retriever already searches. Each chunk is linked to its CodeSymbol (or, for a module docstring, its CodeModule) by a describes edge, so a hit reaches the symbol’s file, line, callers and flows in one hop.Run it after the code graph exists, for example after Step 2 above:dataset(default"main_dataset"): the dataset that holds the code graph, by name or UUID.repo(defaultNone): limit the run to one enola repository label.Nonecovers everyCodeRepositoryin the dataset.include_modules(defaultTrue): also store one chunk per file-level (module) docstring.extract_entities(defaultFalse): also run cognify’s LLM entity extraction and summaries over the chunks before they are stored. The chunks go through onechunks_per_batchslice at a time, so at most one cognify batch of LLM requests runs at once.run_in_background(defaultFalse): return immediately and process in the background.
extract_entities=True also needs an LLM provider.What gets stored. The pipeline creates one CodeDocument per source file with at least one docstring and one DocumentChunk per documented symbol. A chunk’s text is file:line, then qualified_name (kind), then the signature, a blank line and the docstring. A module docstring is anchored at file:1. A docstring too long for one chunk is split on paragraphs, and every piece repeats the header. Python docstrings are read in full from the repository’s source files with ast, which needs the repository’s indexed path to still be a readable directory on the machine running cognee. For other languages, and for every symbol of a repository whose source cannot be read there, the pipeline falls back to enola’s doc field: the first paragraph of the doc comment, cut at 300 bytes. The pinned enola release (0.5.1) fills that field for Python, Go and TypeScript/JavaScript symbols, so symbols in other languages get no docstring chunk; snapshots written by enola releases older than 0.4.30 carry no doc at all. The code graph’s own nodes, hashes and edges are not changed.Re-runs. Ids are derived from content, so re-running over unchanged sources adds no node or edge. A changed docstring replaces exactly its chunk. Chunks that a run no longer produces, along with their documents and summaries, are removed from the graph and from the DocumentChunk_text, CodeDocument_name and TextSummary_text vector collections. Every run still stores and re-embeds every chunk it produces, so an unchanged re-run is not free.The same tasks are available by name through the deprecated memify() API.Query Across Repositories
Query Across Repositories
A dataset’s repositories form one Enola cluster. When a dataset holds two or more code repositories added with See HTTP call relations for how each edge is resolved and what it carries.
add() or remember(), cognify() (and remember(content_type="code")) runs Enola once over all of them, so the graph also holds the edges between them: reaches_route from a client call to the route that serves it, and cross-repository calls / imports. Each repository is still stored under its own data item, so forget(data_id=...) removes exactly one repository. Put repositories that call each other in the same dataset. Repositories in different datasets are searched independently, and no path can connect them.- The cluster snapshot is written to
.enola-<dataset_id>inside each repository, not the.enoladirectory a single-repository run uses, because it holds the other repositories’ facts too. - The Enola timeout for a cluster run is the per-repository timeout multiplied by the number of repositories, capped at one hour, and never lower than one repository’s timeout.
- Each repository is matched to its Enola label by the repository name in its git remote, or else its directory name. If the repositories do not have distinct names, cognee logs a warning and builds each repository’s graph on its own, with no cross-repository links.
- A repository whose directory no longer exists is left out of the cluster.
makes_request links the symbol that makes a call to that call’s route node, and ordinary per-repository ingestion produces it. reaches_route links that route node to the server route it reaches in the other repository, and it only appears when both repositories are in the same dataset. With both in place, impact_analysis on a server handler reaches the client functions that call it, across the repository boundary:Index a Public Repository by URL
Index a Public Repository by URL
A GitHub/GitLab repository URL passed to plain
add() or remember() — with no content_type — is recognised as a repository by its shape, shallow-cloned, and ingested as one code-repo item that takes the same code graph route, plus the repository’s own documents:branch works only on this route: remember() raises ValueError if it is combined with a content_type (so it cannot be paired with repo_credentials) or a session_id. Each branch gets its own clone, but a dataset holds one branch of a URL at a time — adding the URL on another branch re-indexes the code graph, while documents ingested from the previous branch stay until you remove them with forget(). See add() for the errors a missing or invalid branch raises.Use remember(url, content_type="code") instead when you want only the code graph (no repository documents), several repositories in one call, or repo_credentials for a private remote. Clones land under COGNEE_REPOS_DIR (default ~/.cognee/repos) either way, and both paths need git on PATH. Cloning is allowed by default from the SDK and CLI; an API server needs ALLOW_HTTP_REQUESTS=true in its environment. Deeper forge URLs (/blob/, /tree/, /issues, GitLab’s /-/ pages) are still treated as web pages; see add() for the exact detection rules.Tag a Repository with node_set
Tag a Repository with node_set
A
node_set passed with a whole repository — a GitHub/GitLab URL or a local code project directory handed to plain add() or remember() — tags the code graph too, not just the repository’s documents. Every code node, the CodeRepository node included, gets the same belongs_to_set NodeSet edges and source_node_set (the tag names joined with , ) that a document gets, so node-set-scoped queries and the graph view group the repository’s code under its tag:- Only this whole-repository route is tagged. Code files added individually and
remember(content_type="code")leave code nodes untagged, exactly as before. - For a tagged repository the sorted tag names are part of each node’s
fact_hash, so reordering tags does not trigger a rewrite. The next timecognify()processes the repository after a tag is added or changed, it rewrites that repository’s code nodes once — no LLM calls, no migration — even when the enola snapshot itself is unchanged. Re-adding a repository whose code has not changed, with a differentnode_set, does not start that run: itscode_repoitem is already marked processed, socognify()skips it. The new tag is stored and applied the next time the repository’s code changes andcognify()reprocesses it. Untagged repositories keep their existing hashes. - Tags the repository no longer carries are removed: their
belongs_to_setedges are deleted and the names dropped from the nodes. Edges are matched by NodeSet id, so a rename that only changes case, spacing, or apostrophes ("Team-A"→"team-a") keeps the shared edge and only drops the old spelling from the nodes.
Index a Private Repository
Index a Private Repository
remember(url, content_type="code", repo_credentials="<token>") clones a private https remote using an out-of-band token — a GitHub App installation token, for example. It is sent as HTTP basic auth under the x-access-token username, the scheme GitHub expects. The token reaches git through environment-level config rather than the URL, so nothing derived from the URL can carry it: the clone directory name, the persisted git remote, log lines, and git’s own error output all use the credential-free URL. repo_credentials is code-only — passing it with any other content_type raises ValueError.Credentials embedded in the URL userinfo (https://x-access-token:<token>@github.com/org/repo.git) still work, but are the legacy path. Either way, the source recorded on each result item is redacted, so a token never surfaces in a remember() result.To connect a whole organization instead of one repository at a time, see the GitHub integration.One Data Row per Remembered Repository
One Data Row per Remembered Repository
Each repository handed to
remember(content_type="code") is stored as one code_repo data item in the target dataset before its graph is built, and that row’s id comes back on the repository’s result item:id and dataset_id come back as strings; forget() takes UUIDs, so convert them before handing them over — a string reaches forget() as a dataset name and fails the lookup.The id is pinned to (user, dataset, repository path), so remembering the same repository again updates that one row and hands back the same id instead of accreting rows. With run_in_background=True the items fill in as the repositories run, so read them after await result.What the row buys you:forget()can target one repository. The code graph pipeline runs over the stored row, so its graph writes record that row as their owner andforget(data_id=UUID(item["id"]), dataset_id=UUID(result.dataset_id))removes that repository and the nodes it wrote. One caveat: code node ids are keyed on the repository’s directory basename, so two remembered repositories whose directories share a name share nodes, and only the first writer owns the unchanged ones.- The repository shows up on the dataset. The row lists under
GET /api/v1/datasets/{dataset_id}/datalike any other document. A finished repository is also stamped as completed for bothcognify_pipelineandcode_graph_pipeline, so it reads as done onGET /api/v1/datasets/{dataset_id}/processing-status?pipeline=code_graph_pipeline(that is the endpoint carrying per-item status; the data listing carries none), and a latercognify()over the dataset does not rerun enola for it, unless the dataset’s cluster needs a rebuild.
index_vectors setting; the existing ones are rebuilt graph-only. When the dataset already holds more than 5 other repositories, the call builds only the new ones and marks the rest for the next cognify() of the dataset, which rebuilds the whole cluster. Until then, the new repositories have no edges to the deferred ones. The cluster’s Enola run happens before any repository is built, so if it fails, a blocking call with the default raise_on_error=True raises and otherwise every repository in the call is recorded as errored. A failed rebuild of an existing repository leaves the new repositories’ items intact but still sets the result’s status to errored.Deleting one repository (forget(data_id=...) or datasets.delete_data) does not run Enola. It marks the dataset’s remaining repositories for re-extraction, and the next cognify() of the dataset rebuilds them from a fresh snapshot, which drops their links to the deleted repository.When several repositories are remembered in one call, a failing one is recorded as {"status": "errored", "error": ...} on its own item and the batch carries on — that is what background runs and raise_on_error=False callers get, the POST /api/v1/remember route and the GitHub organization sync among them. The result’s status becomes errored with the per-repository messages joined into its error, and the HTTP route answers 409 with that body rather than failing the whole request. A blocking SDK call keeps the default raise_on_error=True and still raises on the first repository that fails outright — a clone, an authentication, or a row write. A graph build that comes back errored never raises: it is recorded on its item and the batch continues under either setting. Either way, a repository that failed after its row was stored still carries its id.Query the Code Graph Through recall()
Query the Code Graph Through recall()
recall() reaches the same deterministic operations without assembling a search() call. The "code" scope is explicit opt-in — neither "auto" nor "all" includes it — and code_query takes the same operation dict this guide uses:code_query runs explore seeded with the query text, and entries come back with source="code", so a scope=["graph", "code"] call keeps the two lanes apart in the results. For the full parameter behavior, see recall().Provide Your Own enola Binary
Provide Your Own enola Binary
Cognee installs the pinned
enola-cli wheel as a core dependency and runs the binary from the current environment’s scripts directory. ENOLA_PATH always wins over that bundled binary, so point it at your own build to control the version — and note the pin exists because the code graph’s known answers are validated against it. Nothing is downloaded at run time; a missing binary raises EnolaNotInstalledError asking you to reinstall cognee. For the full resolution order, see Where the enola binary comes from.Pipelines
How tasks are orchestrated into a pipeline.
run_custom_pipeline()
The full parameter surface of the call this guide uses.
Custom Tasks and Pipelines
Write your own tasks and assemble them into a pipeline.