Skip to content

Run your first query

This tutorial searches a HSSMCortex store that has already been populated. You will confirm the local prerequisites, issue a semantic search, and then compare it with a graph query.

Execution status

Documentation CI strictly builds this page, but it does not execute the runtime query subcommands. They require a populated local Cognee store and configured model credentials; verify them manually against the store you intend to use. The --help check below does not access the store.

Prerequisites

You need:

  • Python 3.11 or newer and uv;
  • a clone of HSSMCortex with uv sync completed;
  • an existing populated Cognee data directory; and
  • ANTHROPIC_API_KEY in the environment or in ~/.secrets/anthropic-api-key.

By default, Cortex reads the store from .cognee/ in the repository. To use a different store, set COGNEE_DATA_PATH before running a query.

1. Confirm the command surface

From the repository root, inspect the installed command:

uv run cortex-query --help

The command lists search, graph, summaries, and ask. This tutorial uses the first two because they expose the distinction between vector retrieval and graph-assisted retrieval most directly.

2. Search paper chunks

Run a semantic search and request three results:

uv run cortex-query search \
  "What likelihood methods are used for drift-diffusion models?" \
  --top-k 3

Successful output begins with 3 result(s) (semantic search) when at least three matches are available. Each result is a chunk from the ingested corpus; it is retrieval context, not a new reviewed Cortex document.

3. Follow an entity through the graph

Now query relationships associated with an entity:

uv run cortex-query graph "drift diffusion model" --top-k 3

Graph results are generated from relationships extracted during ingestion. Use them to discover connections, then verify important claims against the reviewed summary and source paper before relying on them.

4. Try the other retrieval modes

uv run cortex-query summaries "likelihood approximation networks" --top-k 3
uv run cortex-query ask "How do LANs relate to analytic likelihoods?" --top-k 5

summaries searches document-level summaries. ask asks Cognee to combine graph and summary context and may use more model calls; it should not be treated as a canonical publication record.

Troubleshooting

  • No API key: set ANTHROPIC_API_KEY; the CLI exits before configuring Cognee when the key is absent.
  • No results or missing tables: populate the selected store by following Ingest reviewed content.
  • Wrong local store: set COGNEE_DATA_PATH to the directory used during ingestion and retry.