◆ System Architecture

How Kyros works
under the hood

A four-layer architecture purpose-built for AI memory: secure ingestion, cryptographic integrity, intelligent decay, and hybrid vector storage. Click anything to learn exactly what it does — in plain English or technical detail.

4
Architecture Layers
SHA-256
Hash Algorithm
HNSW
Vector Index
RLS
Tenant Isolation
Explanation Mode:Click any layer box to inspect it

System Dataflow Diagram

Trace exactly what happens when you store or recall a memory. Click a flow button, then click any layer to inspect it.

Kyros AI · System Architecture · 4-Layer Stack
🖥️Your Application
01Layer 01
📦

Client SDK Layer

How your code talks to Kyros

▼ Click to inspect
→
02Layer 02
🔐

API Gateway & Security

The front door — every request is verified here

▼ Click to inspect
→
03Layer 03
🧠

Memory Intelligence Engine

The brain — where all the smart work happens

▼ Click to inspect
→
04Layer 04
💾

Hybrid Storage Layer

Where memories live — fast cache + permanent database

▼ Click to inspect
🗄️
PostgreSQL + pgvector
Vector + relational storage
Redis Cache
Hot key caching layer
🌳
Merkle Audit Log
Cryptographic audit trail
Design Principles

Six properties that make Kyros different

Explained simply, so anyone can understand.

🏛️

Tenant Isolation

Every user's memories are completely separated from everyone else's — like private rooms in a building.

🔒

Tamper-Proof Audit

Every memory gets a unique fingerprint. If anyone changes a memory, the fingerprint no longer matches — exposing the tampering.

⏳

Bitemporal History

You can ask 'What did the system know about a user on March 1st?' — and get the exact answer, even months later.

📉

Intelligent Forgetting

Old, irrelevant memories fade away automatically — so the AI doesn't get confused by stale information.

🔍

Semantic Recall

You search by meaning, not keywords. Ask 'tell me about the user's job' and Kyros finds all related memories even if the word 'job' wasn't used.

🌐

Multi-Agent Shared State

Multiple AI agents can share the same memory space — so they always work from the same facts without duplicating work.

Technology Choices

What we use and why

Every technology choice was made deliberately — not just for what it does, but for why it's the right tool for AI memory.

API Framework
FastAPI
Async Python, automatic OpenAPI docs, Pydantic validation
🗄️
Primary Database
PostgreSQL 15
ACID compliance, Row-Level Security, bitemporal columns
🔍
Vector Search
pgvector HNSW
ANN search in-database, no separate vector DB needed
Caching Layer
Redis 7
Sub-millisecond hot key access, TTL-based eviction
🔐
Cryptography
SHA-256 + Merkle
Tamper-evident audit trail, O(log n) proof verification
📉
Memory Decay
Ebbinghaus Model
Psychologically grounded retention weighting
📦
Client SDKs
Python + TypeScript
Native language support for the most common AI stacks
🧮
Embeddings
OpenAI / Local
Pluggable embedding provider — cloud or on-premise
Full Request Lifecycle

From your code to stored memory — every step

A complete walkthrough of a single kyros.ingest() call — what happens inside the system.

01

SDK Call Initiated

Your application calls the SDK. The SDK serializes the request body and injects your API key into the Authorization header automatically.

kyros.ingest(content="User is Alex. Loves Python.", user_id="u123", type="semantic")
02

Gateway Authentication

The gateway validates your API key against its SHA-256 hash. Checks rate limit (default: 1000 req/min). Extracts tenant_id for RLS scoping.

POST /v1/memories/ingest
Authorization: Bearer eyJhbGci...
X-Tenant-ID: org_kyros_abc
03

Hashing & Merkle Append

A deterministic SHA-256 hash is computed from the content. Appended as a new leaf to the Merkle tree. All parent hashes are recalculated bottom-up to produce a new root.

hash = SHA256("User is Alex. Loves Python.") → "sha256_4af1b2c..."
merkle.append(leaf=hash) # Root recalculated
new_root = "sha256_root_e9f3..."
04

Embedding & Decay Init

The content is converted to a high-dimensional vector embedding. Initial retention weight is set to 1.0 (100%). The Ebbinghaus decay constant (λ) is assigned based on memory type.

embedding = embed_model.encode("User is Alex. Loves Python.")
# → [0.021, -0.314, 0.887, ...] (1536 dimensions)
retention_weight = 1.0 # λ=0.003 for semantic type
05

Belief Conflict Check

A BFS traversal over the semantic relationship graph checks for factual contradictions (e.g., if 'User is Bob' already exists). Conflicts are flagged or auto-resolved before write.

# BFS search for semantic contradictions
conflicts = belief_graph.find_contradictions(
 new_content="User is Alex",
 user_id="u123"
)
# → [] (no conflicts found — safe to commit)
06

Database Commit

The complete memory record is written to PostgreSQL. The HNSW vector index is updated for ANN search. The hot embedding is cached in Redis with a TTL for fast subsequent recall.

INSERT INTO memories (
 user_id, content, hash, embedding,
 retention_weight, valid_from, recorded_at, type
) VALUES ('u123', 'User is Alex...', 'sha256_4af1b2c...', '[0.021,...]', 1.0, NOW(), NOW(), 'semantic');
-- HNSW index updated. Redis hot-key cached.

Ready to integrate?

The full API reference documents every endpoint, parameter, and response shape in this architecture.

API Reference →Try the Sandbox