Skip to content

feat: Revise README for installation and CLI usage #1463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Vasilije1990 merged 14 commits into from
Sep 24, 2025
Merged

feat: Revise README for installation and CLI usage #1463

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
2769b5b
feat: Revise README for installation and CLI usage
Vasilije1990 Sep 24, 2025
7620f46
Change section headers from H2 to H4
Vasilije1990 Sep 24, 2025
99efc0b
Update README with usage and installation details
Vasilije1990 Sep 24, 2025
694fc7f
Remove contributors section from README
Vasilije1990 Sep 24, 2025
311085b
Update usage instructions in README
Vasilije1990 Sep 24, 2025
867e216
Enhance README with cognee usage details
Vasilije1990 Sep 24, 2025
e62339d
Revise cognee usage details in README
Vasilije1990 Sep 24, 2025
e286949
Restore contributing section in README.md
Vasilije1990 Sep 24, 2025
8adfa8e
Simplify data sync instructions in README
Vasilije1990 Sep 24, 2025
c4b2ce0
Revise README for self-hosted and hosted platform
Vasilije1990 Sep 24, 2025
6a75a16
Update README.md
Vasilije1990 Sep 24, 2025
9705b09
Revise CLI commands section in README
Vasilije1990 Sep 24, 2025
2437892
Remove beta launch announcement from README
Vasilije1990 Sep 24, 2025
9c3fa87
Revise README for SDK and use-case links
Vasilije1990 Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 68 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,9 @@



**🚀 We launched Cogwit beta (Fully-hosted AI Memory): Sign up [here](https://platform.cognee.ai/)! 🚀**

Build dynamic memory for Agents and replace RAG using scalable, modular ECL (Extract, Cognify, Load) pipelines.

More on [use-cases](https://docs.cognee.ai/use-cases) and [evals](https://github.com/topoteretes/cognee/tree/main/evals)
Build dynamic memory for Agents and replace RAG using scalable, modular ECL (Extract, Cognify, Load) pipelines.

<p align="center">
🌐 Available Languages
Expand Down Expand Up @@ -82,41 +80,41 @@ More on [use-cases](https://docs.cognee.ai/use-cases) and [evals](https://github
Get started quickly with a Google Colab <a href="https://colab.research.google.com/drive/1jHbWVypDgCLwjE71GSXhRL3YxYhCZzG1?usp=sharing">notebook</a> , <a href="https://deepnote.com/workspace/cognee-382213d0-0444-4c89-8265-13770e333c02/project/cognee-demo-78ffacb9-5832-4611-bb1a-560386068b30/notebook/Notebook-1-75b24cda566d4c24ab348f7150792601?utm_source=share-modal&utm_medium=product-shared-content&utm_campaign=notebook&utm_content=78ffacb9-5832-4611-bb1a-560386068b30">Deepnote notebook</a> or <a href="https://github.com/topoteretes/cognee/tree/main/cognee-starter-kit">starter repo</a>


## Using cognee

Self-hosted package:
- Get self-serve UI with embedded Python notebooks
- Add custom tasks and pipelines via Python SDK
- Get Docker images and MCP servers you can deploy
- Use distributed cognee SDK to process a TBs of your data
- Use community adapters to connect to Redis, Azure, Falkor and others

## Contributing
Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.

Hosted platform:
- Sync your local data to our [hosted solution](www.cognee.ai)
- Get a secure API endpoint
- We manage the UI for you

Comment on lines +83 to 96
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix unordered list indentation and improve content clarity.

The static analysis tool identified indentation issues with the unordered lists. Additionally, there's a broken link in line 93.

Apply this diff to fix the indentation and link issues:

 ## Using cognee
 
-Self-hosted package:
- - Get self-serve UI with embedded Python notebooks
- - Add custom tasks and pipelines via Python SDK
- - Get Docker images and MCP servers you can deploy
- - Use distributed cognee SDK to process a TBs of your data
- - Use community adapters to connect to Redis, Azure, Falkor and others
+Self-hosted package:
+- Get self-serve UI with embedded Python notebooks
+- Add custom tasks and pipelines via Python SDK
+- Get Docker images and MCP servers you can deploy
+- Use distributed cognee SDK to process TBs of your data
+- Use community adapters to connect to Redis, Azure, Falkor and others
 
-Hosted platform:
- - Sync your local data to our [hosted solution](www.cognee.ai)
- - Get a secure API endpoint
- - We manage the UI for you
+Hosted platform:
+- Sync your local data to our [hosted solution](https://www.cognee.ai)
+- Get a secure API endpoint
+- We manage the UI for you
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Using cognee
Self-hosted package:
- Get self-serve UI with embedded Python notebooks
- Add custom tasks and pipelines via Python SDK
- Get Docker images and MCP servers you can deploy
- Use distributed cognee SDK to process a TBs of your data
- Use community adapters to connect to Redis, Azure, Falkor and others
## Contributing
Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.
Hosted platform:
- Sync your local data to our [hosted solution](www.cognee.ai)
- Get a secure API endpoint
- We manage the UI for you
## Using cognee
Self-hosted package:
- Get self-serve UI with embedded Python notebooks
- Add custom tasks and pipelines via Python SDK
- Get Docker images and MCP servers you can deploy
- Use distributed cognee SDK to process TBs of your data
- Use community adapters to connect to Redis, Azure, Falkor and others
Hosted platform:
- Sync your local data to our [hosted solution](https://www.cognee.ai)
- Get a secure API endpoint
- We manage the UI for you
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

86-86: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

87-87: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

88-88: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

89-89: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

90-90: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

93-93: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

94-94: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

95-95: Unordered list indentation
Expected: 0; Actual: 1

(MD007, ul-indent)

🤖 Prompt for AI Agents 
In README.md around lines 83 to 96, the unordered list under "Using cognee" has
inconsistent indentation and one broken link; normalize the list indentation so
each bullet is a top-level list item under its section (consistent leading
spaces or no extra indentation), fix the broken hosted solution link by adding
the proper scheme (https://www.cognee.ai), and optionally tighten copy for
clarity (e.g., "Process TBs of data" → "process terabytes of data", "MCP servers
you can deploy" → "deployable MCP servers") while keeping the same bullet
structure.


## Self-Hosted (Open Source)


## 📦 Installation
### 📦 Installation

You can install Cognee using either **pip**, **poetry**, **uv** or any other python package manager.

Cognee supports Python 3.10 to 3.13
Cognee supports Python 3.10 to 3.12

### With pip
#### With uv

```bash
pip install cognee
uv pip install cognee
```

## Local Cognee installation

You can install the local Cognee repo using **uv**, **pip** and **poetry**.
For local pip installation please make sure your pip version is above version 21.3.

### with UV with all optional dependencies

```bash
uv sync --all-extras
```
Detailed instructions can be found in our [docs](https://docs.cognee.ai/getting-started/installation#environment-configuration)

## 💻 Basic Usage
### 💻 Basic Usage

### Setup
#### Setup

```
import os
Expand All @@ -125,10 +123,14 @@ os.environ["LLM_API_KEY"] = "YOUR OPENAI_API_KEY"
```

You can also set the variables by creating .env file, using our <a href="https://github.com/topoteretes/cognee/blob/main/.env.template">template.</a>
To use different LLM providers, for more info check out our <a href="https://docs.cognee.ai">documentation</a>
To use different LLM providers, for more info check out our <a href="https://docs.cognee.ai/setup-configuration/llm-providers">documentation</a>


#### Simple example


### Simple example

##### Python

This script will run the default pipeline:

Expand All @@ -139,13 +141,16 @@ import asyncio

async def main():
# Add text to cognee
await cognee.add("Natural language processing (NLP) is an interdisciplinary subfield of computer science and information retrieval.")
await cognee.add("Cognee turns documents into AI memory.")

# Generate the knowledge graph
await cognee.cognify()

# Add memory algorithms to the graph
await cognee.memify()

# Query the knowledge graph
results = await cognee.search("Tell me about NLP")
results = await cognee.search("What does cognee do?")

# Display the results
for result in results:
Expand All @@ -158,33 +163,38 @@ if __name__ == '__main__':
```
Example output:
```
Natural Language Processing (NLP) is a cross-disciplinary and interdisciplinary field that involves computer science and information retrieval. It focuses on the interaction between computers and human language, enabling machines to understand and process natural language.
Cognee turns documents into AI memory.

```
##### Via CLI

## Our paper is out! <a href="https://arxiv.org/abs/2505.24478" target="_blank" rel="noopener noreferrer">Read here</a>
Let's get the basics covered

<div style="text-align: center">
<img src="assets/cognee-paper.png" alt="cognee paper" width="100%" />
</div>
```
cognee-cli add "Cognee turns documents into AI memory."

</div>
cognee-cli cognify

## Cognee UI
cognee-cli search "What does cognee do?"
cognee-cli delete --all

You can also cognify your files and query using cognee UI.
```
or run
```
cognee-cli -ui
```
Comment on lines +169 to +185
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

🧩 Analysis chain

Add language specification to code blocks and verify CLI command.

The markdown linter identified missing language specifications for the CLI code blocks. Also, verify that the cognee-cli command structure is correct.

Apply this diff to add language specifications:

-```
+```bash
 cognee-cli add "Cognee turns documents into AI memory."
 
 cognee-cli cognify
 
 cognee-cli search "What does cognee do?"
 cognee-cli delete --all

or run
- +bash
cognee-cli -ui

Also verify that the CLI commands are correct:

🏁 Script executed:

#!/bin/bash
# Search for CLI command definitions in the codebase
rg -n "cognee-cli" --type py
fd -t f -e py | xargs rg -l "cli" | head -5

Length of output: 207

🏁 Script executed:

#!/usr/bin/env bash
# Find CLI implementation file(s)
fd 'cli\.py' -e py -t f

# Inspect entry_points for console_scripts in setup.py, setup.cfg, pyproject.toml
rg -n "console_scripts" -g "*.py" -g "setup.cfg" -g "pyproject.toml"

# List click-based commands and options
rg -nP '@click\.(group|command|option)' --type=py

# Detect Typer-based commands
rg -n "Typer" --type=py
rg -nP 'app\.command' --type=py

# Verify UI option usage
rg -n "--ui" --type=py -C2
rg -n "-ui" --type=py -C2

# Check for subcommand definitions
rg -nP '^def (add|cognify|search|delete)\(' --type=py

Length of output: 829

🏁 Script executed:

#!/usr/bin/env bash
# Show the CLI implementation to verify available commands and options
sed -n '1,200p' cognee/cli/minimal_cli.py

# Look for click or typer decorators indicating command definitions
rg -nP '@click\.(group|command|option)' cognee/cli/minimal_cli.py
rg -n 'Typer' -g 'cognee/cli/minimal_cli.py'

Length of output: 3111

🏁 Script executed:

#!/usr/bin/env bash
# Inspect full CLI implementation for command definitions and options
sed -n '1,200p' cognee/cli/_cognee.py

# List all command functions
rg -nP '^def (add|cognify|search|delete|config)\(' -C2 cognee/cli/_cognee.py

# Find --all option definitions
rg -nP '@click\.option.*--all' -C2 cognee/cli/_cognee.py

# Find -ui or --ui option definitions
rg -nP '@click\.option.*(-ui|--ui)' -C2 cognee/cli/_cognee.py

Length of output: 6198

🏁 Script executed:

#!/usr/bin/env bash
# Inspect entry points in pyproject.toml or setup.cfg
rg -n "console_scripts" -g "pyproject.toml"
rg -n "scripts" -g "pyproject.toml" -C3
rg -n "entry_points" -g "pyproject.toml" -C3

# If setup.cfg exists, inspect it
if [ -f setup.cfg ]; then
  sed -n '1,200p' setup.cfg
fi

# If setup.py exists, inspect for entry_points
if [ -f setup.py ]; then
  sed -n '1,200p' setup.py
fi

Length of output: 446

#!/usr/bin/env bash
# Locate and inspect pyproject.toml for console script definition
fd 'pyproject.toml' -t f
sed -n '1,200p' pyproject.toml

# Inspect delete command implementation for --all option
sed -n '1,200p' cognee/cli/commands/delete_command.py
rg -nP 'add_argument.*--all' -C3 cognee/cli/commands/delete_command.py

🏁 Script executed:

#!/usr/bin/env bash
# Locate and inspect pyproject.toml for script definitions
fd pyproject.toml -t f
sed -n '1,200p' pyproject.toml

# Check for Poetry scripts section
rg -n '\[tool\.poetry\.scripts\]' -g pyproject.toml -C2

# Inspect setup.cfg for entry_points
fd setup.cfg -t f
sed -n '1,200p' setup.cfg

# Inspect setup.py for console_scripts
fd setup.py -t f
sed -n '1,200p' setup.py

Length of output: 353

#!/usr/bin/env bash
# Inspect delete_command implementation for --all option
sed -n '1,200p' cognee/cli/commands/delete_command.py

# Search for --all argument in delete_command
rg -nP '\b--all\b' -C2 cognee/cli/commands/delete_command.py

Add bash fences and use correct CLI name
Wrap the snippets in ```bash and replace cognee-cli with `cognee` (the entry point prints usage as `cognee`).

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

173-173: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

183-183: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around lines 169 to 185, the CLI examples are not fenced as bash
and use the wrong binary name; update the fenced code blocks to use ```bash (so
shells get syntax highlighting) and replace every occurrence of `cognee-cli`
with `cognee` in those snippets and the single-line example, leaving surrounding
text unchanged.


<img src="assets/cognee-new-ui.webp" width="100%" alt="Cognee UI 2"></a>

### Running the UI
</div>

Try cognee UI by setting LLM_API_KEY and running ``` cognee-cli -ui ``` command on your terminal.

## Understand our architecture
### Hosted Platform

Get up and running in minutes with automatic updates, analytics, and enterprise security.

1. Sign up on [cogwit](https://www.cognee.ai)
2. Add your API key to local UI and sync your data to Cogwit

<div style="text-align: center">
<img src="assets/cognee_diagram.png" alt="cognee concept diagram" width="100%" />
</div>



Expand All @@ -203,22 +213,26 @@ Try cognee UI by setting LLM_API_KEY and running ``` cognee-cli -ui ``` command
[cognee with local models](https://github.com/user-attachments/assets/8621d3e8-ecb8-4860-afb2-5594f2ee17db)


## Code of Conduct

We are committed to making open source an enjoyable and respectful experience for our community. See <a href="https://github.com/topoteretes/cognee/blob/main/CODE_OF_CONDUCT.md"><code>CODE_OF_CONDUCT</code></a> for more information.

## 💫 Contributors
## Contributing
Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information.

<a href="https://github.com/topoteretes/cognee/graphs/contributors">
<img alt="contributors" src="https://contrib.rocks/image?repo=topoteretes/cognee"/>
</a>

## Sponsors
## Code of Conduct

Thanks to the following companies for sponsoring the ongoing development of cognee.
We are committed to making open source an enjoyable and respectful experience for our community. See <a href="https://github.com/topoteretes/cognee/blob/main/CODE_OF_CONDUCT.md"><code>CODE_OF_CONDUCT</code></a> for more information.

- [GitHub's Secure Open Source Fund](https://resources.github.com/github-secure-open-source-fund/)
## Citation

## Star History
We now have a paper you can cite:

[![Star History Chart](https://api.star-history.com/svg?repos=topoteretes/cognee&type=Date)](https://star-history.com/#topoteretes/cognee&Date)
```bibtex
@misc{markovic2025optimizinginterfaceknowledgegraphs,
title={Optimizing the Interface Between Knowledge Graphs and LLMs for Complex Reasoning},
author={Vasilije Markovic and Lazar Obradovic and Laszlo Hajdu and Jovan Pavlovic},
year={2025},
eprint={2505.24478},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2505.24478},
}
```
Loading