Introduction

In the previous three articles, we started with the memory challenges faced by AI Agents, explored how Cognee addresses these challenges, and examined the unified multimodal computing capabilities provided by CittaBase. In this article, we move from concepts to hands-on practice: deploying Cognee, configuring models, uploading documents, and performing a real retrieval test.

CittaBase, the Cognee backend, and the web interface are deployed on the same server. The chat model and embedding model are accessed through APIs.

01 Environment Preparation

We recommend using a fresh server and ensuring that ports 55432, 8000, and 3000 are available.

Before installation, prepare the API base URLs, model names, API keys, and embedding output dimension for both models. This deployment uses Qwen text-embedding-v4 and deepseek-v4-flash. Qwen text-embedding-v4 generates embeddings, while DeepSeek handles content understanding, entity and relationship extraction, and answer generation.

02 Install CittaBase and Cognee

Run the following commands on the server as root.

Upload the Installation Packages

Create the installation directory:

mkdir -p /opt/install

Upload the following two installation packages to this directory:

ymatrix-ai-1.0.0-1.rocky9.x86_64.rpm
cognee-cittabase.tar.gz

Install Dependencies and the Database

cd /opt/install
dnf module enable -y nodejs:22
dnf install -y nodejs python3.11 python3.11-pip tar gzip
dnf install -y ./ymatrix-ai-1.0.0-1.rocky9.x86_64.rpm
node --version

Execute the commands one at a time and verify that each succeeds before proceeding. The Node.js version should be v22.x.x.

Install Cognee

The application package includes Python dependencies, a prebuilt web interface, and installation tools, so there is no need to compile the application yourself.

Extract the package and check its directory structure:

cd /opt/install
tar -xzf cognee-cittabase.tar.gz
cd cognee-cittabase
python3.11 setup.py --check-package

Once the output confirms Package layout check passed, run:

bash setup.sh

Follow the installation prompts to enter the model parameters:

When entering API keys, the terminal will not display the characters you type. Paste the key and press Enter.

The installer automatically generates the database password and handles application deployment, database initialization, and service startup.

A successful installation displays the following output:

Installation complete.
Database: running
API: ready
UI: ready

If the installation is interrupted, preserve the error messages and the current system state for troubleshooting. Avoid deleting data directories or rerunning the installer without first investigating the cause.

03 Access the Web Interface

By default, the services listen only on the server's loopback interface. You must use an SSH tunnel to access them.

Run the following command on your local computer, replacing the server address and login account as needed:

ssh -N -o ExitOnForwardFailure=yes -L 3000:127.0.0.1:3000 -L 8000:127.0.0.1:8000 root@YOUR_SERVER_IP

Then open the following address in your browser:

http://localhost:3000

After logging in, retain the prefilled local evaluation credentials on the Local instance page and click Sign in.

This configuration is intended for private evaluation and does not require exposing the application ports to the public internet. For shared access in a production environment, configure authentication, TLS, and appropriate network security policies separately.

04 Upload Documents and Verify Q&A

For the initial verification, we recommend using the sample document included in the installation package:

/opt/install/cognee-cittabase/examples/first-test.pdf

You can download the sample PDF from the server to your local computer and then upload it through the browser.

In the web interface, follow these steps:

1. Go to Brain and click Create brain or New brain to create a brain named first-test.
2. Open first-test, click Add files, and upload the sample PDF.
3. Wait for automatic processing to finish. Processing time depends on the model's response speed. Then open Mindmap to inspect the knowledge relationships.
4. Go to Search → Company Brain, select the first-test dataset, and enter the following question:

What is the maintenance interval for the Orion-147 cooling pump?

The expected answer is 45 days, matching the maintenance interval specified in the sample document. If the answer includes source citations, verify them against the original text as well.

In the current release, uploading a document automatically triggers Cognify, so no manual trigger is required. The processing pipeline makes calls to the model APIs.

To check the service status on the server, run:

/opt/cognee/bin/cognee-control status

Once the database, API, and UI are all running normally and document processing and Q&A verification have succeeded, you can import your own materials.

You can also use the MARS3 Bucket document referenced in the previous article to test the following question:

How does MARS3 Bucket reduce Redistribute Motion and enable downstream operators to perform local computation?

05 Common Management Commands

Run the following commands on the server as root:

Avoid starting or stopping services while document processing is in progress.

The services are configured to start automatically at boot. After a server restart, simply re-establish the SSH tunnel to access the web interface.

The configure command supports updating API keys and chat model settings. Saving changes restarts the API service.

Existing vectors are tied to the embedding model, so the tool prevents direct changes to the embedding model, API address, and vector dimension. Such changes require a separate plan for rebuilding or migrating the vectors.

When troubleshooting, start by checking the following items:

Conclusion

At this point, the single-server deployment of CittaBase and Cognee is complete, and knowledge construction and retrieval-based Q&A have been verified using a sample document.

You can now import product manuals, operational records, or business policies, compare retrieved content and knowledge relationships against the original sources, and evaluate how effectively the system supports real-world tasks.