Architecture Overview

CogMem is designed as a framework-agnostic, self-evolving knowledge layer that any AI agent can plug into. At its core is the Knowledge Kernel — a deterministic system that governs how information becomes knowledge. Above it sits the Adaptive Cognitive Plane (ACP) — a control layer that learns how to organize that knowledge more effectively over time.

Design Principles

Contract-First

Core contracts define interfaces without importing provider clients

Provider Isolation

Database clients live behind provider implementations

Event-Driven

Agents communicate via outbox events for loose coupling

Multi-Tenant

Every object scoped by tenant_id for isolation

Structure as Hypothesis

Every structural choice is a testable hypothesis, not a fixed decision

Safe Self-Evolution

All structural changes are proposed, reversible, and auditable

System Layers

┌─────────────────────────────────────────────────────────┐
│                    API Layer                             │
│              FastAPI HTTP + MCP Server                   │
├─────────────────────────────────────────────────────────┤
│             Adaptive Cognitive Plane (ACP)               │
│  Meta-Kernel │ StrategyResolver │ RestructuringExecutor  │
├─────────────────────────────────────────────────────────┤
│                Knowledge Workflows                       │
│   EntityDossier │ TimelineBuilder │ ContradictionReport  │
├─────────────────────────────────────────────────────────┤
│                  Knowledge Kernel                        │
│    Admission │ Transformation │ Conflict │ Maintenance  │
├─────────────────────────────────────────────────────────┤
│                    Contracts                             │
│  ObjectStore │ StrategyStore │ OutcomeStore │ TextSearch │
│  VectorSearch │ GraphSearch │ ProposalStore              │
├─────────────────────────────────────────────────────────┤
│                    Providers                             │
│   Postgres │ OpenSearch │ Neo4j │ Qdrant │ SurrealDB    │
├─────────────────────────────────────────────────────────┤
│                  Agent Subsystem                         │
│  ChunkAgent │ EmbedAgent │ EntityExtract │ ClaimExtract │
└─────────────────────────────────────────────────────────┘

The Adaptive Cognitive Plane is the key addition. It observes how the system performs, evaluates whether the current memory strategy is effective, and proposes structural changes when it detects a better approach — all safely and reversibly.

Data Flow

Ingestion Flow

Query Flow

Self-Evolution Flow

Core Domain Objects

Object	Description	Key Fields
Item	Source document	kos_id, tenant_id, title, content_text, source
Passage	Text chunk	kos_id, item_id, text, span, extraction_method, confidence
Entity	Named entity	kos_id, name, entity_type, aliases, created_from
Claim	Structured assertion	kos_id, subject_entity_id, predicate, object, evidence_passage_ids, confidence, conflicts_with
Artifact	Generated content	kos_id, artifact_type, workflow_id, entity_scope, claim_ids, rendered_content
KernelEvent	Kernel decision log	kos_id, event_type, payload, created_at
MemoryStrategy	Self-evolving knowledge config	kos_id, scope_type, retrieval_policy, document_policy, vector_policy, graph_policy, claim_policy
OutcomeEvent	Feedback signal	kos_id, strategy_id, outcome_type, metrics, source
StrategyChangeProposal	Proposed restructuring	kos_id, base_strategy_id, proposed_strategy_id, risk_level, status

Import Rules

These rules are strictly enforced:

Core contracts must NOT import provider clients (opensearch, neo4j, etc.)
Agents must only import core and contracts
Providers must NOT import FastAPI
Adapters wrap external frameworks (LangChain, CrewAI, etc.)
ACP services must only import core contracts and models — never providers directly

Next Steps

Adaptive Cognitive Plane

How the system evolves itself

Knowledge Kernel

Explore the cognitive core

Contracts

Learn about core interfaces

Knowledge Workflows

See workflow strategies

Start Here

Platform

Architecture

Architecture Overview

Architecture Overview

Design Principles

Contract-First

Provider Isolation

Event-Driven

Multi-Tenant

Structure as Hypothesis

Safe Self-Evolution

System Layers

Data Flow

Ingestion Flow

Query Flow

Self-Evolution Flow

Core Domain Objects

Import Rules

Next Steps

Adaptive Cognitive Plane

Knowledge Kernel

Contracts

Knowledge Workflows

​Architecture Overview

​Design Principles

Contract-First

Provider Isolation

Event-Driven

Multi-Tenant

Structure as Hypothesis

Safe Self-Evolution

​System Layers

​Data Flow

​Ingestion Flow

​Query Flow

​Self-Evolution Flow

​Core Domain Objects

​Import Rules

​Next Steps

Adaptive Cognitive Plane

Knowledge Kernel

Contracts

Knowledge Workflows

Architecture Overview

Design Principles

System Layers

Data Flow

Ingestion Flow

Query Flow

Self-Evolution Flow

Core Domain Objects

Import Rules

Next Steps