# leobaray/memoria architecture

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

- Interactive diagram: https://gitdiagram.com/leobaray/memoria
- Repository: https://github.com/leobaray/memoria

## Overview

memoria is a long-term, evidence-aware memory for an AI coding assistant. Messages trigger card recall; scheduled dream processing learns from Claude Code conversations, updates cards, derives deductions and lessons, and grades outcomes. Separate capabilities collect measured facts, answer questions with cited evidence, evaluate recall, import existing memories, replicate data, and provide a read-only UI. Cards and conversation history are plain files. Edges use excerpts, the SOURCE INDEX, or README statements; unsampled implementation details are not inferred.

Main entry points: [`mem.py`](https://github.com/leobaray/memoria/blob/main/mem.py) (JSON memory cards), [`sonho.py`](https://github.com/leobaray/memoria/blob/main/sonho.py) (Dream consolidation), [`perguntar.py`](https://github.com/leobaray/memoria/blob/main/perguntar.py) (Reasoned answers), [`regua.py`](https://github.com/leobaray/memoria/blob/main/regua.py) (Recall evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recall["Recall and answers"]
  node_recall["Card recall<br/>[mem.py]"]
  node_semantic["Semantic search<br/>[sentido.py]"]
  node_reasoning["Reasoned answers<br/>[perguntar.py]"]
  node_rawsearch["Conversation search<br/>[conversas.py]"]
end

subgraph group_learning["Learning and evaluation"]
  node_dream["Dream consolidation<br/>[sonho.py]"]
  node_extract["Conversation extraction<br/>[extrair.py]"]
  node_collector["Measured collection<br/>[coleta.py]"]
  node_ruler["Recall evaluation<br/>[regua.py]"]
  node_importer["Memory import<br/>[importar.py]"]
end

subgraph group_data["Memory data"]
  node_cards[("JSON memory cards<br/>[mem.py]")]
  node_templates["Card type templates"]
  node_rawdata[("Raw conversations<br/>[conversas.py]")]
  node_history["History and diary<br/>[sonho.py]"]
end

subgraph group_operations["Operations and visibility"]
  node_replication["Memory replication<br/>[replica.py]"]
  node_ui["Read-only memory UI<br/>[ui.py]"]
end

node_assistant(("AI assistant"))
node_messages(("User messages"))
node_model["Claude model"]
node_embeddingservice["Ollama embeddings"]
node_honcho["Honcho memory"]

node_messages -->|"triggers"| node_recall
node_recall -->|"returns context"| node_assistant
node_recall -->|"reads cards"| node_cards
node_recall -->|"searches by meaning"| node_semantic
node_semantic -->|"requests embeddings"| node_embeddingservice
node_reasoning -->|"requests package"| node_recall
node_reasoning -->|"finds similar cards"| node_semantic
node_reasoning -->|"finds similar turns"| node_rawsearch
node_reasoning -->|"prompts answer"| node_model
node_reasoning -->|"returns answer"| node_assistant
node_rawsearch -->|"indexes and searches"| node_rawdata
node_dream -->|"reads new turns"| node_extract
node_dream -->|"learns from conversations"| node_rawdata
node_dream -->|"requests consolidation"| node_model
node_dream -->|"updates cards"| node_cards
node_dream -->|"records history"| node_history
node_dream -->|"deduces and rewards"| node_cards
node_dream -->|"derives lessons"| node_cards
node_collector -->|"writes measurements"| node_cards
node_ruler -->|"tests retrieval"| node_recall
node_ruler -.->|"compares optionally"| node_honcho
node_ruler -->|"grades answers"| node_reasoning
node_importer -->|"imports facts"| node_cards
node_importer -->|"reads conclusions"| node_honcho
node_templates -->|"defines card fields"| node_cards
node_replication -->|"synchronizes data"| node_cards
node_ui -->|"displays cards"| node_cards
node_ui -->|"displays activity"| node_history

click node_recall "https://github.com/leobaray/memoria/blob/main/mem.py"
click node_semantic "https://github.com/leobaray/memoria/blob/main/sentido.py"
click node_reasoning "https://github.com/leobaray/memoria/blob/main/perguntar.py"
click node_rawsearch "https://github.com/leobaray/memoria/blob/main/conversas.py"
click node_dream "https://github.com/leobaray/memoria/blob/main/sonho.py"
click node_extract "https://github.com/leobaray/memoria/blob/main/extrair.py"
click node_collector "https://github.com/leobaray/memoria/blob/main/coleta.py"
click node_ruler "https://github.com/leobaray/memoria/blob/main/regua.py"
click node_importer "https://github.com/leobaray/memoria/blob/main/importar.py"
click node_cards "https://github.com/leobaray/memoria/blob/main/mem.py"
click node_templates "https://github.com/leobaray/memoria/tree/main/esqueletos"
click node_rawdata "https://github.com/leobaray/memoria/blob/main/conversas.py"
click node_history "https://github.com/leobaray/memoria/blob/main/sonho.py"
click node_replication "https://github.com/leobaray/memoria/blob/main/replica.py"
click node_ui "https://github.com/leobaray/memoria/blob/main/ui.py"

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_recall,node_semantic,node_reasoning,node_rawsearch,node_messages toneBlue
class node_dream,node_extract,node_collector,node_ruler,node_importer toneAmber
class node_cards,node_templates,node_rawdata,node_history toneMint
class node_replication,node_ui toneRose
class node_assistant,node_model,node_embeddingservice,node_honcho toneIndigo
```

## Components

### Recall and answers

- [Card recall](https://github.com/leobaray/memoria/blob/main/mem.py): `mem.py`
- [Semantic search](https://github.com/leobaray/memoria/blob/main/sentido.py): `sentido.py`
- [Reasoned answers](https://github.com/leobaray/memoria/blob/main/perguntar.py): `perguntar.py`
- [Conversation search](https://github.com/leobaray/memoria/blob/main/conversas.py): `conversas.py`

### Learning and evaluation

- [Dream consolidation](https://github.com/leobaray/memoria/blob/main/sonho.py): `sonho.py`
- [Conversation extraction](https://github.com/leobaray/memoria/blob/main/extrair.py): `extrair.py`
- [Measured collection](https://github.com/leobaray/memoria/blob/main/coleta.py): `coleta.py`
- [Recall evaluation](https://github.com/leobaray/memoria/blob/main/regua.py): `regua.py`
- [Memory import](https://github.com/leobaray/memoria/blob/main/importar.py): `importar.py`

### Memory data

- [JSON memory cards](https://github.com/leobaray/memoria/blob/main/mem.py): `mem.py`
- [Card type templates](https://github.com/leobaray/memoria/tree/main/esqueletos): `esqueletos`
- [Raw conversations](https://github.com/leobaray/memoria/blob/main/conversas.py): `conversas.py`
- [History and diary](https://github.com/leobaray/memoria/blob/main/sonho.py): `sonho.py`

### Operations and visibility

- [Memory replication](https://github.com/leobaray/memoria/blob/main/replica.py): `replica.py`
- [Read-only memory UI](https://github.com/leobaray/memoria/blob/main/ui.py): `ui.py`

### Other components

- **AI assistant**
- **User messages**
- **Claude model**
- **Ollama embeddings**
- **Honcho memory**

## Connections

- User messages → Card recall: triggers (evidence: `README.md`)
- Card recall → AI assistant: returns context (evidence: `README.md`)
- Card recall → JSON memory cards: reads cards (evidence: `mem.py`)
- Card recall → Semantic search: searches by meaning (evidence: `mem.py`)
- Semantic search → Ollama embeddings: requests embeddings (evidence: `sentido.py`)
- Reasoned answers → Card recall: requests package (evidence: `perguntar.py`)
- Reasoned answers → Semantic search: finds similar cards (evidence: `perguntar.py`)
- Reasoned answers → Conversation search: finds similar turns (evidence: `perguntar.py`)
- Reasoned answers → Claude model: prompts answer (evidence: `perguntar.py`)
- Reasoned answers → AI assistant: returns answer (evidence: `README.md`)
- Conversation search → Raw conversations: indexes and searches (evidence: `conversas.py`)
- Dream consolidation → Conversation extraction: reads new turns (evidence: `README.md`)
- Dream consolidation → Raw conversations: learns from conversations (evidence: `README.md`)
- Dream consolidation → Claude model: requests consolidation (evidence: `sonho.py`)
- Dream consolidation → JSON memory cards: updates cards (evidence: `sonho.py`)
- Dream consolidation → History and diary: records history (evidence: `sonho.py`)
- Dream consolidation → JSON memory cards: deduces and rewards (evidence: `README.md`)
- Dream consolidation → JSON memory cards: derives lessons (evidence: `README.md`)
- Measured collection → JSON memory cards: writes measurements (evidence: `coleta.py`)
- Recall evaluation → Card recall: tests retrieval (evidence: `regua.py`)
- Recall evaluation → Honcho memory: compares optionally (evidence: `regua.py`)
- Recall evaluation → Reasoned answers: grades answers (evidence: `README.md`)
- Memory import → JSON memory cards: imports facts (evidence: `importar.py`)
- Memory import → Honcho memory: reads conclusions (evidence: `importar.py`)
- Card type templates → JSON memory cards: defines card fields (evidence: `README.md`)
- Memory replication → JSON memory cards: synchronizes data (evidence: `replica.py`)
- Read-only memory UI → JSON memory cards: displays cards (evidence: `ui.py`)
- Read-only memory UI → History and diary: displays activity (evidence: `ui.py`)
