# markgatcha/memos architecture

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

- Interactive diagram: https://gitdiagram.com/markgatcha/memos
- Repository: https://github.com/markgatcha/memos

## Overview

MemOS is a local-first persistent memory system for AI agents, centered on a shared SQLite store. The main workflow is an agent or application storing memories through the SDK, then searching and retrieving them across sessions; CLI, MCP, and HTTP are alternate access surfaces. Retrieval combines hybrid search with trust/provenance and can produce cited context packs. Other documented capabilities include ingestion, temporal and graph memory, import/export, image memory, and framework adapters. The graph uses README claims and source-index references; several feature implementations were not sampled, so their internal links are omitted.

Main entry points: [`src/memory.ts`](https://github.com/markgatcha/memos/blob/main/src/memory.ts) (Memory operations), [`src/index.ts`](https://github.com/markgatcha/memos/blob/main/src/index.ts) (TypeScript SDK), [`src/retrieval.ts`](https://github.com/markgatcha/memos/blob/main/src/retrieval.ts) (Hybrid retrieval), [`memos/server/main.py`](https://github.com/markgatcha/memos/blob/main/memos/server/main.py) (Python server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access surfaces"]
  node_sdk["TypeScript SDK<br/>[index.ts]"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP server<br/>[mcp.ts]"]
  node_http["Python HTTP API<br/>[routes.py]"]
  node_pyserver["Python server<br/>[main.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_memorycore["Memory operations<br/>[memory.ts]"]
  node_ingestion["File ingestion<br/>[ingest.ts]"]
  node_temporal["Temporal memory<br/>[temporal.ts]"]
  node_graphmem["Graph memory<br/>[graph.ts]"]
  node_trust["Trust and provenance<br/>[provenance.ts]"]
end

subgraph group_retrieval["Recall and context"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.ts]"]
  node_embeddings["Embedding providers<br/>[embeddings.ts]"]
  node_context["Context packs<br/>[context-pack.ts]"]
  node_citations["Citations<br/>[citations.ts]"]
end

subgraph group_persistence["Local persistence"]
  node_sqlite[("SQLite store<br/>[sqlite.ts]")]
end

subgraph group_integrations["Adapters and extensions"]
  node_externaldata["Memory import/export<br/>[external-import.ts]"]
  node_vision["Image memory<br/>[clip.ts]"]
  node_adapters["Framework adapters"]
end

node_agent(("AI agent"))
node_app(("Application"))

node_agent -->|"uses"| node_sdk
node_app -->|"uses"| node_sdk
node_sdk -->|"exposes"| node_memorycore
node_memorycore -->|"delegates search"| node_retrieval
node_memorycore -->|"persists memories"| node_sqlite
node_memorycore -->|"imports data"| node_externaldata
node_memorycore -->|"uses embeddings"| node_embeddings
node_memorycore -->|"builds packs"| node_context
node_ingestion -->|"stores chunks"| node_memorycore
node_retrieval -->|"weights provenance"| node_trust
node_trust -->|"creates tokens"| node_citations
node_retrieval -.->|"uses vectors"| node_embeddings
node_cli -.->|"accesses"| node_memorycore
node_mcp -.->|"accesses"| node_memorycore
node_http -->|"routes through"| node_pyserver
node_pyserver -.->|"bridges requests"| node_memorycore
node_sdk -->|"offers ingest"| node_ingestion
node_sdk -->|"offers time search"| node_temporal
node_sdk -->|"offers graph memory"| node_graphmem
node_sdk -->|"offers image search"| node_vision
node_sdk -->|"supports integrations"| node_adapters
node_sdk -->|"supports portability"| node_externaldata

click node_sdk "https://github.com/markgatcha/memos/blob/main/src/index.ts"
click node_cli "https://github.com/markgatcha/memos/blob/main/src/cli.ts"
click node_mcp "https://github.com/markgatcha/memos/blob/main/src/mcp.ts"
click node_http "https://github.com/markgatcha/memos/blob/main/memos/server/routes.py"
click node_pyserver "https://github.com/markgatcha/memos/blob/main/memos/server/main.py"
click node_memorycore "https://github.com/markgatcha/memos/blob/main/src/memory.ts"
click node_ingestion "https://github.com/markgatcha/memos/blob/main/src/ingest.ts"
click node_temporal "https://github.com/markgatcha/memos/blob/main/src/temporal.ts"
click node_graphmem "https://github.com/markgatcha/memos/blob/main/src/graph.ts"
click node_trust "https://github.com/markgatcha/memos/blob/main/src/provenance.ts"
click node_retrieval "https://github.com/markgatcha/memos/blob/main/src/retrieval.ts"
click node_embeddings "https://github.com/markgatcha/memos/blob/main/src/embeddings.ts"
click node_context "https://github.com/markgatcha/memos/blob/main/src/context-pack.ts"
click node_citations "https://github.com/markgatcha/memos/blob/main/src/citations.ts"
click node_sqlite "https://github.com/markgatcha/memos/blob/main/src/storage/sqlite.ts"
click node_externaldata "https://github.com/markgatcha/memos/blob/main/src/external-import.ts"
click node_vision "https://github.com/markgatcha/memos/blob/main/src/vision/clip.ts"
click node_adapters "https://github.com/markgatcha/memos/tree/main/src/adapters"

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_sdk,node_cli,node_mcp,node_http,node_pyserver toneBlue
class node_memorycore,node_ingestion,node_temporal,node_graphmem,node_trust toneAmber
class node_retrieval,node_embeddings,node_context,node_citations toneMint
class node_sqlite toneRose
class node_externaldata,node_vision,node_adapters,node_agent,node_app toneIndigo
```

## Components

### Access surfaces

- [TypeScript SDK](https://github.com/markgatcha/memos/blob/main/src/index.ts): `src/index.ts`
- [CLI](https://github.com/markgatcha/memos/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/markgatcha/memos/blob/main/src/mcp.ts): `src/mcp.ts`
- [Python HTTP API](https://github.com/markgatcha/memos/blob/main/memos/server/routes.py): `memos/server/routes.py`
- [Python server](https://github.com/markgatcha/memos/blob/main/memos/server/main.py): `memos/server/main.py`

### Memory lifecycle

- [Memory operations](https://github.com/markgatcha/memos/blob/main/src/memory.ts): `src/memory.ts`
- [File ingestion](https://github.com/markgatcha/memos/blob/main/src/ingest.ts): `src/ingest.ts`
- [Temporal memory](https://github.com/markgatcha/memos/blob/main/src/temporal.ts): `src/temporal.ts`
- [Graph memory](https://github.com/markgatcha/memos/blob/main/src/graph.ts): `src/graph.ts`
- [Trust and provenance](https://github.com/markgatcha/memos/blob/main/src/provenance.ts): `src/provenance.ts`

### Recall and context

- [Hybrid retrieval](https://github.com/markgatcha/memos/blob/main/src/retrieval.ts): `src/retrieval.ts`
- [Embedding providers](https://github.com/markgatcha/memos/blob/main/src/embeddings.ts): `src/embeddings.ts`
- [Context packs](https://github.com/markgatcha/memos/blob/main/src/context-pack.ts): `src/context-pack.ts`
- [Citations](https://github.com/markgatcha/memos/blob/main/src/citations.ts): `src/citations.ts`

### Local persistence

- [SQLite store](https://github.com/markgatcha/memos/blob/main/src/storage/sqlite.ts): `src/storage/sqlite.ts`

### Adapters and extensions

- [Memory import/export](https://github.com/markgatcha/memos/blob/main/src/external-import.ts): `src/external-import.ts`
- [Image memory](https://github.com/markgatcha/memos/blob/main/src/vision/clip.ts): `src/vision/clip.ts`
- [Framework adapters](https://github.com/markgatcha/memos/tree/main/src/adapters): `src/adapters`

### Other components

- **AI agent**
- **Application**

## Connections

- AI agent → TypeScript SDK: uses (evidence: `README.md`)
- Application → TypeScript SDK: uses (evidence: `README.md`)
- TypeScript SDK → Memory operations: exposes (evidence: `src/index.ts`)
- Memory operations → Hybrid retrieval: delegates search (evidence: `src/memory.ts`)
- Memory operations → SQLite store: persists memories (evidence: `src/memory.ts`)
- Memory operations → Memory import/export: imports data (evidence: `src/memory.ts`)
- Memory operations → Embedding providers: uses embeddings (evidence: `src/memory.ts`)
- Memory operations → Context packs: builds packs (evidence: `src/memory.ts`)
- File ingestion → Memory operations: stores chunks (evidence: `src/ingest.ts`)
- Hybrid retrieval → Trust and provenance: weights provenance (evidence: `src/retrieval.ts`)
- Trust and provenance → Citations: creates tokens (evidence: `src/provenance.ts`)
- Hybrid retrieval → Embedding providers: uses vectors
- CLI → Memory operations: accesses
- MCP server → Memory operations: accesses
- Python HTTP API → Python server: routes through (evidence: `memos/server/main.py`)
- Python server → Memory operations: bridges requests
- TypeScript SDK → File ingestion: offers ingest (evidence: `src/index.ts`)
- TypeScript SDK → Temporal memory: offers time search (evidence: `src/index.ts`)
- TypeScript SDK → Graph memory: offers graph memory (evidence: `src/index.ts`)
- TypeScript SDK → Image memory: offers image search (evidence: `README.md`)
- TypeScript SDK → Framework adapters: supports integrations (evidence: `README.md`)
- TypeScript SDK → Memory import/export: supports portability (evidence: `README.md`)