Architecture Overview

Understand Cerememory's layered architecture and crate structure.

System Overview

Cerememory is organized as a layered system where each layer has a single responsibility. Requests flow from external clients through transport bindings, into the engine, and down to the individual memory stores.

plaintext

┌─────────────────────────────────────────────────────────────┐
│                     LLM Applications                         │
│  (Claude, GPT, Gemini, custom agents)                        │
└──────────────┬──────────────┬──────────────┬────────────────┘
               │              │              │
       ┌───────▼───┐   ┌─────▼─────┐   ┌────▼────┐
       │  HTTP/REST │   │   gRPC    │   │   MCP   │
       │  (axum)   │   │  (tonic)  │   │  (rmcp) │
       └───────┬───┘   └─────┬─────┘   └────┬────┘
               │              │              │
               └──────────────┼──────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  CerememoryEngine  │
                    │  (coordinator)     │
                    └─────────┬─────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
   ┌──────▼──────┐   ┌───────▼───────┐   ┌───────▼───────┐
   │ Decay Engine │   │  Association  │   │   Evolution   │
   │ (power-law)  │   │  (spreading   │   │   (adaptive)  │
   │              │   │   activation) │   │               │
   └──────────────┘   └───────────────┘   └───────────────┘
          │                   │                   │
   ┌──────▼───────────────────▼───────────────────▼──────┐
   │                   Five Stores                        │
   │  ┌──────────┐ ┌──────────┐ ┌───────────┐           │
   │  │ Episodic │ │ Semantic │ │ Procedural│           │
   │  │  (redb)  │ │  (redb)  │ │   (redb)  │           │
   │  └──────────┘ └──────────┘ └───────────┘           │
   │  ┌───────────┐ ┌─────────┐                          │
   │  │ Emotional │ │ Working │                          │
   │  │  (redb)   │ │ (memory)│                          │
   │  └───────────┘ └─────────┘                          │
   └─────────────────────────────────────────────────────┘
          │
   ┌──────▼─────────────────────────────────────────────┐
   │              Raw Journal                            │
   │  ┌────────────────────────────────────────────┐    │
   │  │ Raw Store (redb + Tantivy full-text)       │    │
   │  │ Verbatim conversation preservation         │    │
   │  └────────────────────────────────────────────┘    │
   └─────────────────────────────────────────────────────┘

Crate Structure

cerememory

crates

cerememory-core

types.rs

protocol.rs

traits.rs

error.rs

cerememory-engine

cerememory-config

cerememory-decay

cerememory-association

cerememory-evolution

cerememory-index

cerememory-archive

cerememory-store-episodic

cerememory-store-semantic

cerememory-store-procedural

cerememory-store-emotional

cerememory-store-working

cerememory-store-raw

cerememory-store-common

cerememory-transport-http

cerememory-transport-grpc

cerememory-transport-mcp

cerememory-cli

adapters

adapter-claude

adapter-openai

adapter-gemini

adapter-common

Layer Responsibilities

Transport Layer

Three transport bindings expose CMP externally:

HTTP/REST (axum) -- primary network transport. Binds to 127.0.0.1:8420 by default and includes Bearer auth, request IDs, trusted-proxy-aware rate limiting, optional CORS, and opt-in Prometheus metrics.
gRPC (tonic) -- optional network transport. Supports export/import streaming and requires TLS when auth is enabled or the deployment is exposed beyond loopback.
MCP (rmcp) -- stdio transport for Claude Code and MCP-compatible clients. Exposes 15 LLM-friendly tools including store, store_raw, batch_store, batch_store_raw, update, recall, recall_raw, timeline, associate, inspect, forget, dream_tick, consolidate, stats, and export.

Engine Layer

The CerememoryEngine is the central coordinator. It implements encode, recall, lifecycle, and introspect operations and orchestrates cross-store interactions. It manages:

The hippocampal coordinator for cross-store recall and spreading activation
The Tantivy text index and the redb-backed exact cosine vector index
The background decay engine
An optional LLM provider for embeddings, summarization, image/audio handling, and relation extraction

Store Layer

Five specialized curated stores implement the common Store trait:

Episodic
Semantic
Procedural
Emotional
Working

All persistent stores are backed by redb. Working memory is intentionally in-memory only.

A sixth store, the Raw Journal, operates alongside the curated stores. It preserves verbatim conversation content using redb with a dedicated Tantivy full-text search index, enabling forensic recall and dream-tick summarization.

Supporting Engines

Decay Engine -- rayon-parallel power-law decay computation
Association Engine -- spreading activation over the persisted association graph
Evolution Engine -- adaptive tuning surfaced via introspect.evolution

Dependency Direction

text

cerememory-cli
├── cerememory-config
├── cerememory-engine
├── cerememory-transport-*
├── cerememory-archive
└── adapter-*
 
cerememory-core

Next Steps

Five Stores

Deep dive into each brain-inspired memory store

Living Dynamics

Understand decay, noise, emotion, and consolidation