coco-research / cognee

/cognee — Knowledge Graph Memory Backend

A persistent knowledge graph memory system powered by Cognee. Stores entities, decisions, events, and relationships as graph nodes with embeddings, enabling semantic search across projects and sessions.

Quick Reference

COGNEE="http://localhost:8000"   # default; override with COGNEE_BASE_URL

# Status check
curl -s "$COGNEE/health" | jq .

# List datasets
curl -s "$COGNEE/api/v1/datasets" | jq .

# Create a dataset for this project
curl -s -X POST "$COGNEE/api/v1/datasets" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}' | jq .

# Quick semantic search
curl -s -X POST "$COGNEE/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "what did we decide about authentication", "search_type": "FEELING_LUCKY", "top_k": 10}' | jq .

Sub-commands

/cognee status — Health check and dataset overview

Check if Cognee is reachable and show available datasets.

COGNEE="${COGNEE_BASE_URL:-http://localhost:8000}"

echo "=== Cognee Status ==="
HEALTH=$(curl -s -o /dev/null -w "%{http_code}" "$COGNEE/health" 2>/dev/null)
if [ "$HEALTH" = "200" ]; then
    echo "Server:  RUNNING at $COGNEE"
    echo ""
    echo "Datasets:"
    curl -s "$COGNEE/api/v1/datasets" | jq -r '.[] | "  • \(.name) (\(.id))"'
else
    echo "Server:  NOT REACHABLE"
    echo ""
    echo "Start Cognee:"
    echo "  pip install cognee && cognee server start"
fi

/cognee init — Initialize a project dataset

Create a Cognee dataset for the current project.

Procedure:

1. Ask the user for the dataset name (default: current directory name, slugified).
2. Check if a dataset with that name already exists:

curl -s "$COGNEE/api/v1/datasets" | jq -r '.[].name'

1. If it exists: "Dataset 'X' already exists. Using it." → skip creation.
2. If not: create it:

curl -s -X POST "$COGNEE/api/v1/datasets" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$DATASET_NAME\"}" | jq .

1. Confirm:

COGNEE INITIALIZED
==================
Dataset:  {name} ({id})
Endpoint: $COGNEE

Next: Use /cognee-store to push knowledge, /cognee-recall to search.

/cognee switch — Toggle between Brain and Cognee

Switch which memory backend is primary for this project.

Options:

• brain → Use SQLite-based Brain (zero-dependency, per-project)
• cognee → Use Cognee knowledge graph (semantic search, cross-project)
• both → Use both (Brain for quick per-project lookup, Cognee for graph queries)

Behavior:
This sets a preference. Skills that support both backends will check this preference and route accordingly. Default behavior without explicit switch: Brain for local queries, Cognee for cross-project and semantic search.

/cognee graph — View entity relationships

Show the knowledge graph for a specific entity or the current dataset.

# Get dataset ID first
DATASET_ID=$(curl -s "$COGNEE/api/v1/datasets" | jq -r '.[] | select(.name=="my-project") | .id')

# View graph
curl -s "$COGNEE/api/v1/datasets/$DATASET_ID/graph" | jq .

Architecture

Cognee and Brain coexist. They are not mutually exclusive:

┌─────────────────────────────────────┐
│           Coco Agent                │
├─────────────────────────────────────┤
│  /cognee-recall  │  /brain          │
│  /cognee-store   │  /brain-update   │
├─────────────────────────────────────┤
│  Cognee (graph)  │  Brain (SQLite)   │
│  localhost:8000  │  project_brain.db │
└─────────────────────────────────────┘

• Write path: /cognee-store pushes to Cognee; /brain-update pushes to SQLite. You can write to both.
• Read path: /cognee-recall for semantic/graph queries; /brain for structured relational queries.
• No sync between them — they are independent stores. If you need consistency, pick one as primary and use the other as supplementary.

Behavior Rules

Detect Cognee availability

Before any Cognee operation, check the health endpoint. If unreachable:

• Tell the user: "Cognee is not running. Start it with cognee server start or install with pip install cognee."
• Fall back gracefully: offer to use Brain instead for the same operation.

Dataset naming convention

Default dataset name = project directory slug. For example:

• /home/user/MyProject → myproject
• /home/user/E&C → e-and-c

User can override. Ask once, remember the mapping.

Multi-project awareness

Unlike Brain (one DB per project folder), Cognee datasets are namespaced. An agent working across multiple projects can query multiple datasets in a single search:

curl -s -X POST "$COGNEE/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication decisions", "datasets": ["project-a", "project-b"], "search_type": "FEELING_LUCKY"}' | jq .

Prerequisites

Cognee must be installed and running:

pip install cognee
cognee server start

Verify: curl http://localhost:8000/health