# sreenav14/memoire architecture

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

- Interactive diagram: https://gitdiagram.com/sreenav14/memoire
- Repository: https://github.com/sreenav14/memoire

## Overview

Memoire turns uploaded documents and saved chats into evidence-grounded, evolving memory, then answers questions with citations. Users enter through the React UI; authentication and space management are handled by the Auth API, while the Memory API exposes chat, search, document, note, profile, and inference-rule operations. Background jobs extract and chunk content, build a knowledge graph, consolidate facts, and apply inference rules. Query retrieval combines vector recall, graph expansion, and evidence packing. The README documents the service-level flow; unsampled router and retrieval implementations are represented by their documented responsibilities.

Main entry points: [`apps/worker/worker.py`](https://github.com/sreenav14/memoire/blob/main/apps/worker/worker.py) (Job worker), [`apps/services/memory/app/main.py`](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/main.py) (Memory API app), [`apps/services/auth/main.py`](https://github.com/sreenav14/memoire/blob/main/apps/services/auth/main.py) (Auth API), [`apps/web/src/api/client.js`](https://github.com/sreenav14/memoire/blob/main/apps/web/src/api/client.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_web_routes["Web routes<br/>[routes.jsx]"]
  node_login_page["Login page<br/>[LoginPage.jsx]"]
  node_auth_store["Auth state<br/>[auth.js]"]
  node_app_page["Memory workspace<br/>[AppPage.jsx]"]
  node_workspace_ui["Workspace layout<br/>[App.jsx]"]
  node_composer["Chat composer<br/>[BottomComposer.jsx]"]
  node_web_client["API client<br/>[client.js]"]
end

subgraph group_identity["Identity and spaces"]
  node_auth_api["Auth API<br/>[main.py]"]
  node_auth_logic["JWT and passwords<br/>[auth.py]"]
  node_auth_models["Identity models<br/>[models.py]"]
end

subgraph group_memory_api["Memory API"]
  node_memory_app["Memory API app<br/>[main.py]"]
  node_chat_query["Chat answers<br/>[chats.py]"]
  node_chat_save["Save chats<br/>[chat_save.py]"]
  node_documents["Documents<br/>[documents.py]"]
  node_notes["Notes<br/>[notes.py]"]
  node_search["Vector search<br/>[search.py]"]
  node_profiles["Profiles<br/>[profile.py]"]
  node_rule_api["Inference rules API<br/>[inference_rules.py]"]
  node_retrieval["Grounded retrieval"]
end

subgraph group_worker["Background processing"]
  node_worker_loop["Job worker<br/>[worker.py]"]
  node_ingestion["Text ingestion"]
  node_graph_extract["Graph extraction<br/>[extract_hybrid.py]"]
  node_graph_persist["Graph persistence<br/>[persist.py]"]
  node_consolidation["Fact consolidation<br/>[consolidate.py]"]
  node_inference["Rule inference<br/>[infer_engine.py]"]
  node_rule_discovery["Rule discovery<br/>[discovery.py]"]
  node_rule_generation["Rule generation<br/>[generator.py]"]
  node_rule_storage["Rule storage<br/>[storage.py]"]
end

subgraph group_data["Memory data"]
  node_database[("PostgreSQL, pgvector, AGE")]
end

node_user(("User"))

node_user -->|"uses"| node_web_routes
node_web_routes -->|"routes to"| node_login_page
node_web_routes -->|"protects route"| node_app_page
node_app_page -->|"renders"| node_workspace_ui
node_workspace_ui -->|"renders"| node_composer
node_login_page -->|"updates token"| node_auth_store
node_web_client -->|"reads token"| node_auth_store
node_web_client -->|"calls auth"| node_auth_api
node_web_client -->|"calls memory"| node_memory_app
node_auth_api -->|"uses"| node_auth_logic
node_auth_api -->|"queries and creates"| node_auth_models
node_auth_api -->|"reads and writes"| node_database
node_memory_app -->|"registers"| node_chat_query
node_memory_app -->|"registers"| node_chat_save
node_memory_app -->|"registers"| node_documents
node_memory_app -->|"registers"| node_notes
node_memory_app -->|"registers"| node_search
node_memory_app -->|"registers"| node_profiles
node_memory_app -->|"registers"| node_rule_api
node_chat_query -->|"retrieves evidence"| node_retrieval
node_search -->|"queries vectors"| node_database
node_retrieval -->|"reads vectors and graph"| node_database
node_documents -->|"queues ingestion"| node_database
node_chat_save -->|"queues ingestion"| node_database
node_worker_loop -->|"claims jobs"| node_database
node_worker_loop -->|"processes documents"| node_ingestion
node_worker_loop -->|"extracts graph facts"| node_graph_extract
node_worker_loop -->|"persists extraction"| node_graph_persist
node_graph_persist -->|"writes graph evidence"| node_database
node_worker_loop -->|"consolidates facts"| node_consolidation
node_worker_loop -->|"runs rules"| node_inference
node_inference -->|"reads rules, writes edges"| node_database
node_worker_loop -->|"discovers relations"| node_rule_discovery
node_worker_loop -->|"suggests rules"| node_rule_generation
node_worker_loop -->|"stores suggestions"| node_rule_storage
node_rule_api -->|"manages rules"| node_database
node_consolidation -->|"updates fact lifecycle"| node_database
node_ingestion -->|"stores chunks"| node_database

click node_web_routes "https://github.com/sreenav14/memoire/blob/main/apps/web/src/app/routes.jsx"
click node_login_page "https://github.com/sreenav14/memoire/blob/main/apps/web/src/pages/LoginPage.jsx"
click node_auth_store "https://github.com/sreenav14/memoire/blob/main/apps/web/src/store/auth.js"
click node_app_page "https://github.com/sreenav14/memoire/blob/main/apps/web/src/pages/AppPage.jsx"
click node_workspace_ui "https://github.com/sreenav14/memoire/blob/main/apps/web/src/App.jsx"
click node_composer "https://github.com/sreenav14/memoire/blob/main/apps/web/src/components/chat/BottomComposer.jsx"
click node_web_client "https://github.com/sreenav14/memoire/blob/main/apps/web/src/api/client.js"
click node_auth_api "https://github.com/sreenav14/memoire/blob/main/apps/services/auth/main.py"
click node_auth_logic "https://github.com/sreenav14/memoire/blob/main/apps/services/auth/auth.py"
click node_auth_models "https://github.com/sreenav14/memoire/blob/main/apps/services/auth/models.py"
click node_memory_app "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/main.py"
click node_chat_query "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/chats.py"
click node_chat_save "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/chat_save.py"
click node_documents "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/documents.py"
click node_notes "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/notes.py"
click node_search "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/search.py"
click node_profiles "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/profile.py"
click node_rule_api "https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/inference_rules.py"
click node_retrieval "https://github.com/sreenav14/memoire/tree/main/apps/services/memory/app/utils/retrieval"
click node_worker_loop "https://github.com/sreenav14/memoire/blob/main/apps/worker/worker.py"
click node_ingestion "https://github.com/sreenav14/memoire/tree/main/apps/worker/ingestion"
click node_graph_extract "https://github.com/sreenav14/memoire/blob/main/apps/worker/graph/extract_hybrid.py"
click node_graph_persist "https://github.com/sreenav14/memoire/blob/main/apps/worker/graph/persist.py"
click node_consolidation "https://github.com/sreenav14/memoire/blob/main/apps/worker/evolution/consolidate.py"
click node_inference "https://github.com/sreenav14/memoire/blob/main/apps/worker/evolution/infer_engine.py"
click node_rule_discovery "https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/discovery.py"
click node_rule_generation "https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/generator.py"
click node_rule_storage "https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/storage.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_web_routes,node_login_page,node_auth_store,node_app_page,node_workspace_ui,node_composer,node_web_client,node_user toneBlue
class node_auth_api,node_auth_logic,node_auth_models toneAmber
class node_memory_app,node_chat_query,node_chat_save,node_documents,node_notes,node_search,node_profiles,node_rule_api,node_retrieval toneMint
class node_worker_loop,node_ingestion,node_graph_extract,node_graph_persist,node_consolidation,node_inference,node_rule_discovery,node_rule_generation,node_rule_storage toneRose
class node_database toneIndigo
```

## Components

### Web interface

- [Web routes](https://github.com/sreenav14/memoire/blob/main/apps/web/src/app/routes.jsx): `apps/web/src/app/routes.jsx`
- [Login page](https://github.com/sreenav14/memoire/blob/main/apps/web/src/pages/LoginPage.jsx): `apps/web/src/pages/LoginPage.jsx`
- [Auth state](https://github.com/sreenav14/memoire/blob/main/apps/web/src/store/auth.js): `apps/web/src/store/auth.js`
- [Memory workspace](https://github.com/sreenav14/memoire/blob/main/apps/web/src/pages/AppPage.jsx): `apps/web/src/pages/AppPage.jsx`
- [Workspace layout](https://github.com/sreenav14/memoire/blob/main/apps/web/src/App.jsx): `apps/web/src/App.jsx`
- [Chat composer](https://github.com/sreenav14/memoire/blob/main/apps/web/src/components/chat/BottomComposer.jsx): `apps/web/src/components/chat/BottomComposer.jsx`
- [API client](https://github.com/sreenav14/memoire/blob/main/apps/web/src/api/client.js): `apps/web/src/api/client.js`

### Identity and spaces

- [Auth API](https://github.com/sreenav14/memoire/blob/main/apps/services/auth/main.py): `apps/services/auth/main.py`
- [JWT and passwords](https://github.com/sreenav14/memoire/blob/main/apps/services/auth/auth.py): `apps/services/auth/auth.py`
- [Identity models](https://github.com/sreenav14/memoire/blob/main/apps/services/auth/models.py): `apps/services/auth/models.py`

### Memory API

- [Memory API app](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/main.py): `apps/services/memory/app/main.py`
- [Chat answers](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/chats.py): `apps/services/memory/app/routers/chats.py`
- [Save chats](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/chat_save.py): `apps/services/memory/app/routers/chat_save.py`
- [Documents](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/documents.py): `apps/services/memory/app/routers/documents.py`
- [Notes](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/notes.py): `apps/services/memory/app/routers/notes.py`
- [Vector search](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/search.py): `apps/services/memory/app/routers/search.py`
- [Profiles](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/profile.py): `apps/services/memory/app/routers/profile.py`
- [Inference rules API](https://github.com/sreenav14/memoire/blob/main/apps/services/memory/app/routers/inference_rules.py): `apps/services/memory/app/routers/inference_rules.py`
- [Grounded retrieval](https://github.com/sreenav14/memoire/tree/main/apps/services/memory/app/utils/retrieval): `apps/services/memory/app/utils/retrieval`

### Background processing

- [Job worker](https://github.com/sreenav14/memoire/blob/main/apps/worker/worker.py): `apps/worker/worker.py`
- [Text ingestion](https://github.com/sreenav14/memoire/tree/main/apps/worker/ingestion): `apps/worker/ingestion`
- [Graph extraction](https://github.com/sreenav14/memoire/blob/main/apps/worker/graph/extract_hybrid.py): `apps/worker/graph/extract_hybrid.py`
- [Graph persistence](https://github.com/sreenav14/memoire/blob/main/apps/worker/graph/persist.py): `apps/worker/graph/persist.py`
- [Fact consolidation](https://github.com/sreenav14/memoire/blob/main/apps/worker/evolution/consolidate.py): `apps/worker/evolution/consolidate.py`
- [Rule inference](https://github.com/sreenav14/memoire/blob/main/apps/worker/evolution/infer_engine.py): `apps/worker/evolution/infer_engine.py`
- [Rule discovery](https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/discovery.py): `apps/worker/rules/discovery.py`
- [Rule generation](https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/generator.py): `apps/worker/rules/generator.py`
- [Rule storage](https://github.com/sreenav14/memoire/blob/main/apps/worker/rules/storage.py): `apps/worker/rules/storage.py`

### Memory data

- **PostgreSQL, pgvector, AGE**

### Other components

- **User**

## Connections

- User → Web routes: uses (evidence: `README.md`)
- Web routes → Login page: routes to (evidence: `apps/web/src/app/routes.jsx`)
- Web routes → Memory workspace: protects route (evidence: `apps/web/src/app/routes.jsx`)
- Memory workspace → Workspace layout: renders (evidence: `apps/web/src/pages/AppPage.jsx`)
- Workspace layout → Chat composer: renders (evidence: `apps/web/src/App.jsx`)
- Login page → Auth state: updates token (evidence: `apps/web/src/pages/LoginPage.jsx`)
- API client → Auth state: reads token (evidence: `apps/web/src/api/client.js`)
- API client → Auth API: calls auth (evidence: `README.md`)
- API client → Memory API app: calls memory (evidence: `README.md`)
- Auth API → JWT and passwords: uses (evidence: `apps/services/auth/main.py`)
- Auth API → Identity models: queries and creates (evidence: `apps/services/auth/main.py`)
- Auth API → PostgreSQL, pgvector, AGE: reads and writes (evidence: `apps/services/auth/main.py`)
- Memory API app → Chat answers: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Save chats: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Documents: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Notes: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Vector search: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Profiles: registers (evidence: `apps/services/memory/app/main.py`)
- Memory API app → Inference rules API: registers (evidence: `apps/services/memory/app/main.py`)
- Chat answers → Grounded retrieval: retrieves evidence (evidence: `README.md`)
- Vector search → PostgreSQL, pgvector, AGE: queries vectors (evidence: `apps/services/memory/app/routers/search.py`)
- Grounded retrieval → PostgreSQL, pgvector, AGE: reads vectors and graph (evidence: `README.md`)
- Documents → PostgreSQL, pgvector, AGE: queues ingestion (evidence: `README.md`)
- Save chats → PostgreSQL, pgvector, AGE: queues ingestion (evidence: `README.md`)
- Job worker → PostgreSQL, pgvector, AGE: claims jobs (evidence: `apps/worker/worker.py`)
- Job worker → Text ingestion: processes documents (evidence: `apps/worker/worker.py`)
- Job worker → Graph extraction: extracts graph facts (evidence: `apps/worker/worker.py`)
- Job worker → Graph persistence: persists extraction (evidence: `apps/worker/worker.py`)
- Graph persistence → PostgreSQL, pgvector, AGE: writes graph evidence (evidence: `README.md`)
- Job worker → Fact consolidation: consolidates facts (evidence: `apps/worker/worker.py`)
- Job worker → Rule inference: runs rules (evidence: `apps/worker/worker.py`)
- Rule inference → PostgreSQL, pgvector, AGE: reads rules, writes edges (evidence: `apps/worker/evolution/infer_engine.py`)
- Job worker → Rule discovery: discovers relations (evidence: `apps/worker/worker.py`)
- Job worker → Rule generation: suggests rules (evidence: `apps/worker/worker.py`)
- Job worker → Rule storage: stores suggestions (evidence: `apps/worker/worker.py`)
- Inference rules API → PostgreSQL, pgvector, AGE: manages rules (evidence: `apps/services/memory/app/routers/inference_rules.py`)
- Fact consolidation → PostgreSQL, pgvector, AGE: updates fact lifecycle (evidence: `README.md`)
- Text ingestion → PostgreSQL, pgvector, AGE: stores chunks (evidence: `README.md`)