Redis — Overview

OWNER: gerco (infrastructure) ALSO_USED_BY: urszula, maxim (application usage) LAST_VERIFIED: 2026-03-26 GE_STACK_VERSION: Redis 7.4

---

Overview

Redis is GE's message broker and ephemeral cache layer. It powers all agent-to-agent communication via Redis Streams. Agents writing code that touches Redis MUST read this section first.

CRITICAL: GE Redis Runs on Port 6381

CHECK: Agent is connecting to Redis. IF: Connection string uses port 6379 (the Redis default). THEN: WRONG. GE Redis runs on port 6381. Read config/ports.yaml for authoritative port mapping.

ANTI_PATTERN: Hardcoding localhost:6379 anywhere in the codebase. FIX: Read the port from config/ports.yaml or the REDIS_PORT environment variable.

Role in GE Architecture

Redis serves two distinct roles in GE:

Role	Mechanism	Data Lifetime
Message Broker	Redis Streams	Until consumed + trimmed (MAXLEN)
Ephemeral Cache	Key-value with TTL	Until TTL expires or evicted

PostgreSQL is SSOT. Redis is never the source of truth for anything. If Redis loses data, the system recovers from PostgreSQL. If PostgreSQL loses data, the system is broken.

CHECK: Agent is storing data in Redis. IF: The data has no other persistent copy (not in PostgreSQL, not in filesystem). THEN: STOP. Redis is volatile. Persist to PostgreSQL first, cache in Redis second.

Agent Communication Flow

Admin UI → XADD ge:work:incoming
         → ge-orchestrator reads, routes
         → XADD triggers.{agent_name}
         → ge-executor reads, executes
         → Completion written (COMP-*.md)
         → Host cron syncs to PostgreSQL

All inter-agent messaging flows through Redis Streams. No agent communicates directly with another agent — the orchestrator routes everything.

READ_ALSO: wiki/docs/stack/redis/streams.md

Authentication

Redis in GE requires a password. The password is stored in the ge-secrets Kubernetes secret, key redis-password.

CHECK: Agent is configuring a Redis client. IF: Client connects without authentication. THEN: It will fail. Read the password from the ge-secrets secret or the REDIS_PASSWORD environment variable.

Connection Configuration

Setting	Value	Reason
Port	6381	Non-default to avoid conflicts
Max memory	256MB	Single-node k3s, shared resources
Eviction policy	allkeys-lru	Prevents OOM when cache is full
Persistence	AOF (appendonly yes)	Stream data survives restart
Max connections	100	k3s resource constraint

Version

GE runs Redis 7.4 on k3s. Do NOT use Redis 8.x features (XACKDEL, idempotent XADD) — they are not available.

CHECK: Agent is using a Redis command. IF: Command was introduced in Redis 8.0 or later. THEN: Not available. Find a Redis 7.4-compatible alternative.

GE-Specific Conventions

• Port 6381 — Not 6379. Ever.
• PostgreSQL is SSOT — Redis is a cache and message bus, never the source of truth.
• MAXLEN on every XADD — No unbounded streams. See streams.md.
• Password required — From ge-secrets Kubernetes secret.
• No KEYS command — Use SCAN if you must iterate. KEYS blocks the event loop.
• No Lua scripts in application code — Orchestrator may use Lua; application agents do not.

Cross-References

READ_ALSO: wiki/docs/stack/redis/streams.md READ_ALSO: wiki/docs/stack/redis/caching.md READ_ALSO: wiki/docs/stack/redis/patterns.md READ_ALSO: wiki/docs/stack/redis/pitfalls.md READ_ALSO: wiki/docs/stack/redis/checklist.md