Skip to content
Floe

ADR-0046: Agent Memory Architecture (Cognee Integration)

Status

Section titled “Status”

Proposed - Epic 10A

Context

Section titled “Context”

AI coding agents (Claude Code, Cursor, etc.) contributing to the floe codebase lose context during compaction cycles. This creates several problems:

  • Decision amnesia: Reasoning behind “why not Alternative B” is lost
  • Session recovery overhead: 5-10 minutes of manual context reconstruction
  • Capability blindness: Agents don’t know “have we solved this before?”
  • Isolated sessions: Cross-session learning doesn’t persist

Target Persona: AI coding agents and human maintainers contributing TO the floe codebase.

Not For: End users of floe (Platform Engineers, Data Engineers).

Decision

Section titled “Decision”

Integrate Cognee Cloud as persistent, graph-augmented memory for AI coding agents contributing to the floe codebase.

Why Cognee?

Section titled “Why Cognee?”
AlternativeProsConsDecision
Vector-only RAGSimple, fastNo relationships, flatRejected
Neo4j + embeddingsPowerful graphsSelf-hosted, complexRejected
CogneeGraph + vectors, MCP support, SaaSCloud dependencySelected
LangGraph/LangMemGood toolingLess graph-nativeRejected

Key Decisions

Section titled “Key Decisions”
  1. Cognee Cloud (SaaS) over self-hosted: Shared team knowledge, no infrastructure burden
  2. Graph-augmented RAG over vector-only: Relationships between decisions matter
  3. MCP integration over custom CLI: Native Claude Code support
  4. Async git hooks over sync: Non-blocking, don’t slow commits

Implementation

Section titled “Implementation”

Package Location

Section titled “Package Location”
devtools/                              # INTERNAL ONLY - never distributed
└── agent-memory/                      # Cognee integration
    ├── pyproject.toml                 # "Private :: Do Not Upload" classifier
    └── src/agent_memory/              # Package code

Why devtools/?

  • Signals “not for distribution” (vs packages/ which are published)
  • Common pattern for internal tooling
  • Installed via [project.optional-dependencies].dev only
  • CI excludes from production artifacts

Integration Points

Section titled “Integration Points”
┌─────────────────┐       ┌─────────────────┐
│  Claude Code    │──MCP──│  Cognee Cloud   │
│  (AI Agent)     │       │  (Knowledge     │
└────────┬────────┘       │   Graph)        │
         │                └────────┬────────┘
         │                         │
    ┌─────────▼─────────┐     ┌────▼────┐
    │ local agent config│     │ docs/   │
    │ MCP connection    │     │ ADRs    │
    └───────────────────┘     │ Rules   │
                              └─────────┘

Cognification Pipeline

Section titled “Cognification Pipeline”
  1. Architecture docs: All ADRs, constitution, rules indexed with relationships
  2. Docstrings: Python docstrings extracted, linked to architecture concepts
  3. Decisions: Git commit messages with decision context preserved
  4. Sessions: Session state persisted for recovery after compaction

MCP Tools

Section titled “MCP Tools”

Cognee MCP server exposes three tools to Claude Code:

  • cognify: Add content to knowledge graph
  • search: Query knowledge graph
  • codify: Generate code from knowledge

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  • Cross-session context preservation (no more “what were we doing?”)
  • Decision traceability (“why did we choose Dagster over Airflow?”)
  • Capability discovery (“have we implemented something like this?”)
  • Shared team knowledge (all contributors access same graph)

Negative

Section titled “Negative”
  • Cloud dependency (Cognee Cloud availability)
  • API costs (batch processing mitigates)
  • Sync latency (async hooks, eventual consistency)

Mitigations

Section titled “Mitigations”
RiskMitigation
Cloud dependencyCognee has SLA, data export available
API costsBatch processing, selective cognify
Hook performanceAsync execution, don’t block commits
Knowledge noiseCareful ontology design, validation

Security

Section titled “Security”
  • Cognee API key stored in GitHub secrets + .cognee/config.yaml (gitignored)
  • No secrets committed to knowledge graph
  • Data classification: Internal development context only

References

Section titled “References”