# sparkhello/memory_platform architecture

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

- Interactive diagram: https://gitdiagram.com/sparkhello/memory_platform
- Repository: https://github.com/sparkhello/memory_platform

## Overview

Memory Platform is a local-first memory proxy between OpenAI-compatible chat clients and model providers. Its main workflow routes a chat turn through Memory Gateway, recalls relevant memories, sends the request to Model Gateway for provider routing, then conservatively extracts and stores eligible facts after the answer. The product also includes an administrative web console, explicit MCP and REST knowledge access, and an Android-hosted runtime. Some subsystem links are documented in the README; source excerpts and the index support the implementation links shown here, but unsampled internals are not inferred.

Main entry points: [`services/memory-gateway/app/main.py`](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/main.py) (HTTP app), [`services/memory-gateway/app/api/chat_gateway.py`](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/api/chat_gateway.py) (Chat endpoint), [`services/model-gateway/model_gateway/service.py`](https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/service.py) (Model API), [`services/memory-gateway/app/llm/client.py`](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_memory["Memory Gateway"]
  node_gateway["HTTP app<br/>[main.py]"]
  node_chat["Chat endpoint<br/>[chat_gateway.py]"]
  node_recall["Memory search<br/>[search.py]"]
  node_ingest["Fact extraction<br/>[ingest.py]"]
  node_memstore[("Memory store<br/>[repository.py]")]
  node_auth["Access tokens<br/>[tokens.py]"]
  node_llmclient["LLM client<br/>[client.py]"]
  node_runtime["Model runtime<br/>[runtime.py]"]
  node_embedding["Embedding contract"]
  node_usage["Usage attribution<br/>[attribution.py]"]
end

subgraph group_model["Model Gateway"]
  node_modelservice["Model API<br/>[service.py]"]
  node_routing["Request routing<br/>[routing.py]"]
  node_control["Control plane<br/>[control_plane.py]"]
  node_configstore[("Gateway config<br/>[config_store.py]")]
end

subgraph group_knowledge["Knowledge Access"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_knowledgeagent["Knowledge agent<br/>[agent.py]"]
  node_retrieval["Document retrieval<br/>[retrieval.py]"]
end

subgraph group_console["Administration"]
  node_webui["Web console<br/>[App.tsx]"]
end

subgraph group_android["Android Runtime"]
  node_androidservice["Background service<br/>[GatewayService.kt]"]
  node_embedded["Embedded stack<br/>[embedded_stack.py]"]
end

node_client(("Chat client"))
node_provider(("Model provider"))

node_client -->|"sends chat"| node_gateway
node_gateway -->|"routes requests"| node_chat
node_chat -.->|"recalls memories"| node_recall
node_chat -.->|"requests completion"| node_llmclient
node_llmclient -->|"resolves route"| node_runtime
node_llmclient -->|"posts request"| node_modelservice
node_modelservice -->|"routes model"| node_routing
node_modelservice -->|"serves control API"| node_control
node_modelservice -->|"reads configuration"| node_configstore
node_routing -.->|"dispatches upstream"| node_provider
node_chat -.->|"extracts after answer"| node_ingest
node_ingest -->|"resolves and saves"| node_memstore
node_recall -.->|"queries memories"| node_memstore
node_gateway -->|"authenticates requests"| node_auth
node_gateway -->|"mounts console"| node_webui
node_client -.->|"uses optional tools"| node_mcp
node_mcp -->|"uses knowledge tools"| node_knowledgeagent
node_mcp -->|"searches documents"| node_retrieval
node_knowledgeagent -.->|"selects excerpts"| node_retrieval
node_androidservice -->|"starts and stops"| node_embedded

click node_gateway "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/main.py"
click node_chat "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/api/chat_gateway.py"
click node_recall "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/search.py"
click node_ingest "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/ingest.py"
click node_memstore "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/store/repository.py"
click node_auth "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/auth/tokens.py"
click node_llmclient "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/client.py"
click node_runtime "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/runtime.py"
click node_embedding "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/embedding_contract.py"
click node_usage "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/usage/attribution.py"
click node_modelservice "https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/service.py"
click node_routing "https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/routing.py"
click node_control "https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/control_plane.py"
click node_configstore "https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/config_store.py"
click node_mcp "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/mcp_server/server.py"
click node_knowledgeagent "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/knowledge/agent.py"
click node_retrieval "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/knowledge/retrieval.py"
click node_webui "https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/ui/src/App.tsx"
click node_androidservice "https://github.com/sparkhello/memory_platform/blob/main/apps/android/app/src/main/java/app/memoryplatform/android/GatewayService.kt"
click node_embedded "https://github.com/sparkhello/memory_platform/blob/main/apps/android/app/src/main/python/embedded_stack.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_gateway,node_chat,node_recall,node_ingest,node_memstore,node_auth,node_llmclient,node_runtime,node_embedding,node_usage,node_client toneBlue
class node_modelservice,node_routing,node_control,node_configstore toneAmber
class node_mcp,node_knowledgeagent,node_retrieval toneMint
class node_webui toneRose
class node_androidservice,node_embedded,node_provider toneIndigo
```

## Components

### Memory Gateway

- [HTTP app](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/main.py): `services/memory-gateway/app/main.py`
- [Chat endpoint](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/api/chat_gateway.py): `services/memory-gateway/app/api/chat_gateway.py`
- [Memory search](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/search.py): `services/memory-gateway/app/memory/search.py`
- [Fact extraction](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/ingest.py): `services/memory-gateway/app/memory/ingest.py`
- [Memory store](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/memory/store/repository.py): `services/memory-gateway/app/memory/store/repository.py`
- [Access tokens](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/auth/tokens.py): `services/memory-gateway/app/auth/tokens.py`
- [LLM client](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/client.py): `services/memory-gateway/app/llm/client.py`
- [Model runtime](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/runtime.py): `services/memory-gateway/app/llm/runtime.py`
- [Embedding contract](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/llm/embedding_contract.py): `services/memory-gateway/app/llm/embedding_contract.py`
- [Usage attribution](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/usage/attribution.py): `services/memory-gateway/app/usage/attribution.py`

### Model Gateway

- [Model API](https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/service.py): `services/model-gateway/model_gateway/service.py`
- [Request routing](https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/routing.py): `services/model-gateway/model_gateway/routing.py`
- [Control plane](https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/control_plane.py): `services/model-gateway/model_gateway/control_plane.py`
- [Gateway config](https://github.com/sparkhello/memory_platform/blob/main/services/model-gateway/model_gateway/config_store.py): `services/model-gateway/model_gateway/config_store.py`

### Knowledge Access

- [MCP tools](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/mcp_server/server.py): `services/memory-gateway/app/mcp_server/server.py`
- [Knowledge agent](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/knowledge/agent.py): `services/memory-gateway/app/knowledge/agent.py`
- [Document retrieval](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/app/knowledge/retrieval.py): `services/memory-gateway/app/knowledge/retrieval.py`

### Administration

- [Web console](https://github.com/sparkhello/memory_platform/blob/main/services/memory-gateway/ui/src/App.tsx): `services/memory-gateway/ui/src/App.tsx`

### Android Runtime

- [Background service](https://github.com/sparkhello/memory_platform/blob/main/apps/android/app/src/main/java/app/memoryplatform/android/GatewayService.kt): `apps/android/app/src/main/java/app/memoryplatform/android/GatewayService.kt`
- [Embedded stack](https://github.com/sparkhello/memory_platform/blob/main/apps/android/app/src/main/python/embedded_stack.py): `apps/android/app/src/main/python/embedded_stack.py`

### Other components

- **Chat client**
- **Model provider**

## Connections

- Chat client → HTTP app: sends chat
- HTTP app → Chat endpoint: routes requests (evidence: `services/memory-gateway/app/main.py`)
- Chat endpoint → Memory search: recalls memories
- Chat endpoint → LLM client: requests completion
- LLM client → Model runtime: resolves route (evidence: `services/memory-gateway/app/llm/client.py`)
- LLM client → Model API: posts request (evidence: `services/memory-gateway/app/llm/client.py`)
- Model API → Request routing: routes model (evidence: `services/model-gateway/model_gateway/service.py`)
- Model API → Control plane: serves control API (evidence: `services/model-gateway/model_gateway/service.py`)
- Model API → Gateway config: reads configuration (evidence: `services/model-gateway/model_gateway/service.py`)
- Request routing → Model provider: dispatches upstream
- Chat endpoint → Fact extraction: extracts after answer
- Fact extraction → Memory store: resolves and saves (evidence: `services/memory-gateway/app/memory/ingest.py`)
- Memory search → Memory store: queries memories
- HTTP app → Access tokens: authenticates requests (evidence: `services/memory-gateway/app/main.py`)
- HTTP app → Web console: mounts console (evidence: `services/memory-gateway/app/main.py`)
- Chat client → MCP tools: uses optional tools
- MCP tools → Knowledge agent: uses knowledge tools (evidence: `services/memory-gateway/app/mcp_server/server.py`)
- MCP tools → Document retrieval: searches documents (evidence: `services/memory-gateway/app/mcp_server/server.py`)
- Knowledge agent → Document retrieval: selects excerpts
- Background service → Embedded stack: starts and stops (evidence: `apps/android/app/src/main/java/app/memoryplatform/android/GatewayService.kt`)
