Getting Started with Cognee: Docker Setup and AI Agent Memory Tutorial

🚀 Getting Started with Cognee: Docker Setup & First Agent Memory

I'll be honest — when I first tried to set up a memory system for my AI agents, I spent two days fighting with configurations. Different databases, embedding services, custom middleware... it was a mess. Cognee promised "one command deployment," and I was skeptical. Turns out, it actually delivers.

In this tutorial, I'll walk you through getting Cognee running with Docker, connecting it to an LLM, and giving your first agent persistent memory — all in under 10 minutes.

📋 Prerequisites

• Docker installed (I'm using Docker 27.x on Ubuntu 24.04)
• An LLM API key (OpenAI, Anthropic, or a local model via Ollama)
• About 4GB of free RAM (Cognee + the knowledge graph engine)
• A terminal — no GUI needed once it's running

Step 1: Pull and Run Cognee

This is the part that surprised me — it's literally one command:

docker run -d \
  --name cognee \
  -p 8080:8080 \
  -v $(pwd)/cognee_data:/data \
  -e OPENAI_API_KEY=sk-your-key-here \
  cognee/cognee:latest

⏱️ This takes about 30 seconds to pull the image. Take a coffee break — it'll be ready when you're back.

💡 Why I chose port 8080: It's the default, so you don't need to reconfigure anything. If it conflicts with something else (I had Jenkins on 8080), just change it to 8090 or whatever works for you.

Step 2: Verify It's Running

Check the logs to make sure everything started properly:

docker logs cognee --tail 20

You should see something like Cognee server started on port 8080 near the end. If you see errors about the API key, double-check your OPENAI_API_KEY environment variable.

Now test the API:

curl -s http://localhost:8080/health | python3 -m json.tool

✅ Expected output: A JSON response with {"status": "ok"}. If you see this — congratulations, Cognee is alive. If not, check the logs or the port mapping.

Step 3: Store Your First Memory

Let's give Cognee something to remember. Using the Python SDK (install it with pip install cognee), we'll store a memory and retrieve it:

import cognee

# Connect to your running Cognee instance
client = cognee.CogneeClient(base_url="http://localhost:8080")

# Store a memory
memory_id = client.add_memory(
    agent_id="my-first-agent",
    content="The user prefers concise responses with code examples. They hate marketing fluff.",
    memory_type="semantic",
    user_id="user-123"
)
print(f"Memory stored with ID: {memory_id}")

# Retrieve it later
memories = client.get_memories(
    agent_id="my-first-agent",
    query="How does the user like their answers?",
    user_id="user-123"
)
for m in memories:
    print(f"  → {m['content']} (confidence: {m['score']:.2f})")

⚠️ A mistake I made: I forgot to pass memory_type="semantic" the first time, and Cognee defaulted to episodic. That's fine for most use cases, but if you're storing user preferences (semantic knowledge), specifying the type gives better retrieval accuracy.

Step 4: Cross-Session Memory — The Real Magic

Here's where Cognee shines. Close your terminal, open a new one, and run this:

import cognee

client = cognee.CogneeClient(base_url="http://localhost:8080")

# New session - but Cognee still remembers!
memories = client.get_memories(
    agent_id="my-first-agent",
    query="What did the user tell me about their preferences?",
    user_id="user-123"
)

if memories:
    print("✅ Cognee remembered:")
    for m in memories:
        print(f"   \"{m['content']}\"")
else:
    print("❌ Nothing found - check your setup")

If everything worked, Cognee should return the memory you stored in Step 3 — even though this is a completely new Python session. This is cross-session persistence, and it's the whole point of Cognee.

🎯 Pro Tips From My Experience

🔧 Troubleshooting

Problem: Cognee starts but returns empty results
Fix: Make sure user_id matches between storage and retrieval — I wasted 20 minutes on this because I used "user-123" in one call and "user123" in another.

Problem: Docker container exits immediately
Fix: Check the API key. Cognee needs at least one LLM provider configured to start. Set OPENAI_API_KEY or ANTHROPIC_API_KEY in the environment.

Problem: Memory retrieval is slow on first request
Fix: This is normal — Cognee initializes the knowledge graph engine on first use. Subsequent requests are much faster (cold start: ~2s, subsequent: ~200ms in my testing).

💭 Wrapping Up

Getting Cognee running took me less than 5 minutes, and having persistent agent memory completely changed how I build AI applications. No more stateless agents that forget everything between conversations. No more hacking together custom memory solutions that barely work.

If you're building AI agents and haven't solved the memory problem yet, give Cognee a try. Start with the Docker command above, store a memory, close the session, open a new one, and see that memory still there. That moment when it clicks? That's when you realize how much you were missing.