# juzzydee/oneiro architecture

> Architecture diagram of the GitHub repository juzzydee/oneiro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juzzydee/oneiro
- Repository: https://github.com/juzzydee/oneiro

## Overview

Oneiro is a cognitive-memory service exposed through authenticated MCP tools and scheduled Worker jobs. Its main interaction is: a model captures an episodic memory, encoding turns it into semantic knowledge, distillation selects standing orientation, and recall returns orientation plus relevant memories. Memory storage, embeddings, and vector search support these stages; separate scheduled processes consolidate and calibrate memory. The tree and README establish several capabilities whose implementation was not sampled, so their subsystem nodes are shown without speculative internal wiring.

Main entry points: [`src/worker_store.rs`](https://github.com/juzzydee/oneiro/blob/master/src/worker_store.rs) (Memory store), [`src/worker_encode.rs`](https://github.com/juzzydee/oneiro/blob/master/src/worker_encode.rs) (Episodic encoding), [`src/worker_wake.rs`](https://github.com/juzzydee/oneiro/blob/master/src/worker_wake.rs) (Scheduled jobs), [`src/worker_mcp.rs`](https://github.com/juzzydee/oneiro/blob/master/src/worker_mcp.rs) (Hybrid recall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP access"]
  node_worker["Worker entry<br/>[lib.rs]"]
  node_mcp_endpoint["MCP endpoint<br/>[worker_mcp.rs]"]
  node_auth_context["Request auth<br/>[worker_auth_ctx.rs]"]
  node_oauth["OAuth<br/>[worker_oauth.rs]"]
end

subgraph group_memory["Memory lifecycle"]
  node_memory_store[("Memory store<br/>[worker_store.rs]")]
  node_recall["Hybrid recall<br/>[worker_mcp.rs]"]
  node_embed["Embedding<br/>[worker_embed.rs]"]
  node_encode["Episodic encoding<br/>[worker_encode.rs]"]
  node_batch_encode["Batch encoding"]
  node_orient["Orientation distil"]
  node_decay["Decay and access<br/>[worker_store.rs]"]
end

subgraph group_cognition["Cognitive loops"]
  node_cscc["Semantic defrag<br/>[worker_cscc.rs]"]
  node_rem["REM consolidation<br/>[worker_rem.rs]"]
  node_dialectic["Dialectic review"]
  node_audit["Audit records"]
end

subgraph group_platform["Worker platform"]
  node_d1[("D1 database")]
  node_vectorize[("Vector index")]
  node_scheduler["Scheduled jobs<br/>[worker_wake.rs]"]
  node_kv[("Worker KV")]
end

node_model(("Model client"))
node_claude_api(("Claude API"))

node_model -->|"sends requests"| node_worker
node_worker -->|"validates bearer"| node_auth_context
node_worker -->|"dispatches MCP"| node_mcp_endpoint
node_auth_context -->|"checks OAuth"| node_oauth
node_oauth -->|"validates token"| node_kv
node_mcp_endpoint -->|"handles recall"| node_recall
node_mcp_endpoint -->|"handles memory tools"| node_memory_store
node_recall -->|"loads candidates"| node_memory_store
node_recall -->|"embeds query"| node_embed
node_recall -->|"searches vectors"| node_vectorize
node_embed -.->|"requests embeddings"| node_claude_api
node_encode -.->|"requests judgments"| node_claude_api
node_encode -->|"writes lineage"| node_memory_store
node_encode -->|"embeds semantics"| node_embed
node_encode -->|"upserts vectors"| node_vectorize
node_batch_encode -->|"runs encoding"| node_encode
node_orient -.->|"requests synthesis"| node_claude_api
node_orient -->|"reads and writes"| node_memory_store
node_decay -->|"updates strength"| node_memory_store
node_scheduler -->|"starts scheduled job"| node_cscc
node_scheduler -->|"starts scheduled job"| node_orient
node_scheduler -->|"starts scheduled job"| node_dialectic
node_scheduler -->|"starts scheduled job"| node_rem
node_cscc -->|"loads and merges"| node_memory_store
node_cscc -->|"clusters vectors"| node_vectorize
node_cscc -.->|"judges clusters"| node_claude_api
node_rem -->|"consolidates memories"| node_memory_store
node_rem -.->|"requests decisions"| node_claude_api
node_dialectic -->|"reviews orientation"| node_memory_store
node_dialectic -.->|"runs dialogue"| node_claude_api
node_dialectic -->|"records run"| node_audit
node_audit -->|"writes audit rows"| node_d1
node_memory_store -->|"reads and writes"| node_d1

click node_worker "https://github.com/juzzydee/oneiro/blob/master/src/lib.rs"
click node_mcp_endpoint "https://github.com/juzzydee/oneiro/blob/master/src/worker_mcp.rs"
click node_auth_context "https://github.com/juzzydee/oneiro/blob/master/src/worker_auth_ctx.rs"
click node_oauth "https://github.com/juzzydee/oneiro/blob/master/src/worker_oauth.rs"
click node_memory_store "https://github.com/juzzydee/oneiro/blob/master/src/worker_store.rs"
click node_recall "https://github.com/juzzydee/oneiro/blob/master/src/worker_mcp.rs"
click node_embed "https://github.com/juzzydee/oneiro/blob/master/src/worker_embed.rs"
click node_encode "https://github.com/juzzydee/oneiro/blob/master/src/worker_encode.rs"
click node_batch_encode "https://github.com/juzzydee/oneiro/blob/master/src/worker_encode_batch.rs"
click node_orient "https://github.com/juzzydee/oneiro/blob/master/src/worker_orient_distill.rs"
click node_decay "https://github.com/juzzydee/oneiro/blob/master/src/worker_store.rs"
click node_cscc "https://github.com/juzzydee/oneiro/blob/master/src/worker_cscc.rs"
click node_rem "https://github.com/juzzydee/oneiro/blob/master/src/worker_rem.rs"
click node_dialectic "https://github.com/juzzydee/oneiro/blob/master/src/worker_dialectic.rs"
click node_audit "https://github.com/juzzydee/oneiro/blob/master/src/worker_dialectic_audit.rs"
click node_scheduler "https://github.com/juzzydee/oneiro/blob/master/src/worker_wake.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_worker,node_mcp_endpoint,node_auth_context,node_oauth,node_model toneBlue
class node_memory_store,node_recall,node_embed,node_encode,node_batch_encode,node_orient,node_decay toneAmber
class node_cscc,node_rem,node_dialectic,node_audit,node_claude_api toneMint
class node_d1,node_vectorize,node_scheduler,node_kv toneRose
```

## Components

### MCP access

- [Worker entry](https://github.com/juzzydee/oneiro/blob/master/src/lib.rs): `src/lib.rs`
- [MCP endpoint](https://github.com/juzzydee/oneiro/blob/master/src/worker_mcp.rs): `src/worker_mcp.rs`
- [Request auth](https://github.com/juzzydee/oneiro/blob/master/src/worker_auth_ctx.rs): `src/worker_auth_ctx.rs`
- [OAuth](https://github.com/juzzydee/oneiro/blob/master/src/worker_oauth.rs): `src/worker_oauth.rs`

### Memory lifecycle

- [Memory store](https://github.com/juzzydee/oneiro/blob/master/src/worker_store.rs): `src/worker_store.rs`
- [Hybrid recall](https://github.com/juzzydee/oneiro/blob/master/src/worker_mcp.rs): `src/worker_mcp.rs`
- [Embedding](https://github.com/juzzydee/oneiro/blob/master/src/worker_embed.rs): `src/worker_embed.rs`
- [Episodic encoding](https://github.com/juzzydee/oneiro/blob/master/src/worker_encode.rs): `src/worker_encode.rs`
- [Batch encoding](https://github.com/juzzydee/oneiro/blob/master/src/worker_encode_batch.rs): `src/worker_encode_batch.rs`
- [Orientation distil](https://github.com/juzzydee/oneiro/blob/master/src/worker_orient_distill.rs): `src/worker_orient_distill.rs`
- [Decay and access](https://github.com/juzzydee/oneiro/blob/master/src/worker_store.rs): `src/worker_store.rs`

### Cognitive loops

- [Semantic defrag](https://github.com/juzzydee/oneiro/blob/master/src/worker_cscc.rs): `src/worker_cscc.rs`
- [REM consolidation](https://github.com/juzzydee/oneiro/blob/master/src/worker_rem.rs): `src/worker_rem.rs`
- [Dialectic review](https://github.com/juzzydee/oneiro/blob/master/src/worker_dialectic.rs): `src/worker_dialectic.rs`
- [Audit records](https://github.com/juzzydee/oneiro/blob/master/src/worker_dialectic_audit.rs): `src/worker_dialectic_audit.rs`

### Worker platform

- **D1 database**
- **Vector index**
- [Scheduled jobs](https://github.com/juzzydee/oneiro/blob/master/src/worker_wake.rs): `src/worker_wake.rs`
- **Worker KV**

### Other components

- **Model client**
- **Claude API**

## Connections

- Model client → Worker entry: sends requests
- Worker entry → Request auth: validates bearer
- Worker entry → MCP endpoint: dispatches MCP
- Request auth → OAuth: checks OAuth
- OAuth → Worker KV: validates token
- MCP endpoint → Hybrid recall: handles recall
- MCP endpoint → Memory store: handles memory tools
- Hybrid recall → Memory store: loads candidates
- Hybrid recall → Embedding: embeds query
- Hybrid recall → Vector index: searches vectors
- Embedding → Claude API: requests embeddings
- Episodic encoding → Claude API: requests judgments
- Episodic encoding → Memory store: writes lineage
- Episodic encoding → Embedding: embeds semantics
- Episodic encoding → Vector index: upserts vectors
- Batch encoding → Episodic encoding: runs encoding
- Orientation distil → Claude API: requests synthesis
- Orientation distil → Memory store: reads and writes
- Decay and access → Memory store: updates strength
- Scheduled jobs → Semantic defrag: starts scheduled job
- Scheduled jobs → Orientation distil: starts scheduled job
- Scheduled jobs → Dialectic review: starts scheduled job
- Scheduled jobs → REM consolidation: starts scheduled job
- Semantic defrag → Memory store: loads and merges
- Semantic defrag → Vector index: clusters vectors
- Semantic defrag → Claude API: judges clusters
- REM consolidation → Memory store: consolidates memories
- REM consolidation → Claude API: requests decisions
- Dialectic review → Memory store: reviews orientation
- Dialectic review → Claude API: runs dialogue
- Dialectic review → Audit records: records run
- Audit records → D1 database: writes audit rows
- Memory store → D1 database: reads and writes