# evsio0n/minizep architecture

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

- Interactive diagram: https://gitdiagram.com/evsio0n/minizep
- Repository: https://github.com/evsio0n/minizep

## Overview

minizep is a temporal knowledge-graph memory service for AI agents. An agent submits text through MCP or REST; the service checks access, then ingests an episode, uses an LLM to extract entities, facts, and invalidations, and records time-bounded knowledge with episode provenance. Agents can query current or historical facts through hybrid keyword/vector retrieval with graph-aware reranking. The product also provides asynchronous ingestion, access management, a web UI, persistent memory backends, and a stdio-to-HTTP bridge. Some subsystem links reflect README capabilities because their source was not sampled.

Main entry points: [`src/server/service.ts`](https://github.com/evsio0n/minizep/blob/main/src/server/service.ts) (Memory service), [`src/server/app.ts`](https://github.com/evsio0n/minizep/blob/main/src/server/app.ts) (HTTP application), [`src/store/memory-store.ts`](https://github.com/evsio0n/minizep/blob/main/src/store/memory-store.ts) (Graph store API), [`src/index.ts`](https://github.com/evsio0n/minizep/blob/main/src/index.ts) (Minizep API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP server<br/>[mcp.ts]"]
  node_stdio["stdio transport<br/>[stdio.ts]"]
  node_proxy["stdio HTTP bridge<br/>[stdio-proxy.ts]"]
  node_httpapp["HTTP application<br/>[app.ts]"]
  node_rest["REST API<br/>[rest.ts]"]
  node_tools["MCP tools<br/>[tools.ts]"]
  node_ui["Web UI<br/>[ui.ts]"]
end

subgraph group_service["Service layer"]
  node_service["Memory service<br/>[service.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_access["Access control<br/>[access.ts]"]
  node_jobs["Ingestion jobs<br/>[queue.ts]"]
end

subgraph group_memory["Memory engine"]
  node_core["Minizep API<br/>[index.ts]"]
  node_ingest["Episode ingestion<br/>[ingest.ts]"]
  node_search["Hybrid retrieval<br/>[retrieval.ts]"]
  node_rerank["Graph reranking<br/>[rerank.ts]"]
  node_model["Temporal model<br/>[types.ts]"]
end

subgraph group_storage["Memory storage"]
  node_storeapi["Graph store API<br/>[memory-store.ts]"]
  node_memstore[("Memory graph<br/>[memory-store.ts]")]
  node_pgstore[("Postgres graph<br/>[postgres-store.ts]")]
  node_persistence["Snapshot persistence<br/>[persistence.ts]"]
end

subgraph group_providers["Model providers"]
  node_provider["Provider interfaces<br/>[interfaces.ts]"]
  node_llm["LLM providers<br/>[openai-llm.ts]"]
  node_embed["Embedding providers<br/>[openai-embedder.ts]"]
end

node_agent(("AI agent"))
node_llmservice(("LLM service"))
node_embeddingservice(("Embedding service"))

node_agent -->|"sends MCP"| node_mcp
node_agent -->|"sends HTTP"| node_httpapp
node_agent -.->|"uses stdio"| node_proxy
node_proxy -.->|"forwards requests"| node_httpapp
node_mcp -->|"uses transport"| node_stdio
node_mcp -->|"dispatches tools"| node_tools
node_httpapp -->|"dispatches REST"| node_rest
node_httpapp -->|"dispatches MCP"| node_mcp
node_httpapp -->|"serves UI"| node_ui
node_httpapp -->|"routes requests"| node_service
node_httpapp -->|"checks identity"| node_auth
node_tools -->|"invokes operations"| node_service
node_rest -->|"invokes operations"| node_service
node_ui -->|"calls UI API"| node_rest
node_service -->|"resolves groups"| node_auth
node_service -->|"manages access"| node_access
node_service -->|"calls memory API"| node_core
node_service -->|"queues ingestion"| node_jobs
node_service -->|"persists snapshots"| node_persistence
node_core -->|"ingests episodes"| node_ingest
node_core -->|"retrieves facts"| node_search
node_search -->|"reranks candidates"| node_rerank
node_core -->|"reads and writes"| node_storeapi
node_ingest -->|"writes graph"| node_storeapi
node_ingest -->|"extracts facts"| node_llm
node_ingest -->|"embeds records"| node_embed
node_search -->|"reads graph"| node_storeapi
node_search -->|"embeds query"| node_embed
node_storeapi -->|"uses memory backend"| node_memstore
node_storeapi -.->|"uses database backend"| node_pgstore
node_persistence -->|"snapshots graph"| node_memstore
node_memstore -->|"stores temporal records"| node_model
node_pgstore -->|"stores temporal records"| node_model
node_llm -->|"implements provider"| node_provider
node_embed -->|"implements provider"| node_provider
node_llm -.->|"calls completion API"| node_llmservice
node_embed -.->|"requests vectors"| node_embeddingservice

click node_mcp "https://github.com/evsio0n/minizep/blob/main/src/server/mcp.ts"
click node_stdio "https://github.com/evsio0n/minizep/blob/main/src/server/stdio.ts"
click node_proxy "https://github.com/evsio0n/minizep/blob/main/src/server/stdio-proxy.ts"
click node_httpapp "https://github.com/evsio0n/minizep/blob/main/src/server/app.ts"
click node_rest "https://github.com/evsio0n/minizep/blob/main/src/server/rest.ts"
click node_tools "https://github.com/evsio0n/minizep/blob/main/src/server/tools.ts"
click node_ui "https://github.com/evsio0n/minizep/blob/main/src/server/ui.ts"
click node_service "https://github.com/evsio0n/minizep/blob/main/src/server/service.ts"
click node_auth "https://github.com/evsio0n/minizep/blob/main/src/server/auth.ts"
click node_access "https://github.com/evsio0n/minizep/blob/main/src/server/access.ts"
click node_jobs "https://github.com/evsio0n/minizep/blob/main/src/jobs/queue.ts"
click node_core "https://github.com/evsio0n/minizep/blob/main/src/index.ts"
click node_ingest "https://github.com/evsio0n/minizep/blob/main/src/pipeline/ingest.ts"
click node_search "https://github.com/evsio0n/minizep/blob/main/src/search/retrieval.ts"
click node_rerank "https://github.com/evsio0n/minizep/blob/main/src/search/rerank.ts"
click node_model "https://github.com/evsio0n/minizep/blob/main/src/model/types.ts"
click node_storeapi "https://github.com/evsio0n/minizep/blob/main/src/store/memory-store.ts"
click node_memstore "https://github.com/evsio0n/minizep/blob/main/src/store/memory-store.ts"
click node_pgstore "https://github.com/evsio0n/minizep/blob/main/src/store/postgres-store.ts"
click node_persistence "https://github.com/evsio0n/minizep/blob/main/src/store/persistence.ts"
click node_provider "https://github.com/evsio0n/minizep/blob/main/src/provider/interfaces.ts"
click node_llm "https://github.com/evsio0n/minizep/blob/main/src/provider/openai-llm.ts"
click node_embed "https://github.com/evsio0n/minizep/blob/main/src/provider/openai-embedder.ts"

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_mcp,node_stdio,node_proxy,node_httpapp,node_rest,node_tools,node_ui toneBlue
class node_service,node_auth,node_access,node_jobs toneAmber
class node_core,node_ingest,node_search,node_rerank,node_model toneMint
class node_storeapi,node_memstore,node_pgstore,node_persistence toneRose
class node_provider,node_llm,node_embed,node_agent,node_llmservice,node_embeddingservice toneIndigo
```

## Components

### Agent interfaces

- [MCP server](https://github.com/evsio0n/minizep/blob/main/src/server/mcp.ts): `src/server/mcp.ts`
- [stdio transport](https://github.com/evsio0n/minizep/blob/main/src/server/stdio.ts): `src/server/stdio.ts`
- [stdio HTTP bridge](https://github.com/evsio0n/minizep/blob/main/src/server/stdio-proxy.ts): `src/server/stdio-proxy.ts`
- [HTTP application](https://github.com/evsio0n/minizep/blob/main/src/server/app.ts): `src/server/app.ts`
- [REST API](https://github.com/evsio0n/minizep/blob/main/src/server/rest.ts): `src/server/rest.ts`
- [MCP tools](https://github.com/evsio0n/minizep/blob/main/src/server/tools.ts): `src/server/tools.ts`
- [Web UI](https://github.com/evsio0n/minizep/blob/main/src/server/ui.ts): `src/server/ui.ts`

### Service layer

- [Memory service](https://github.com/evsio0n/minizep/blob/main/src/server/service.ts): `src/server/service.ts`
- [Authentication](https://github.com/evsio0n/minizep/blob/main/src/server/auth.ts): `src/server/auth.ts`
- [Access control](https://github.com/evsio0n/minizep/blob/main/src/server/access.ts): `src/server/access.ts`
- [Ingestion jobs](https://github.com/evsio0n/minizep/blob/main/src/jobs/queue.ts): `src/jobs/queue.ts`

### Memory engine

- [Minizep API](https://github.com/evsio0n/minizep/blob/main/src/index.ts): `src/index.ts`
- [Episode ingestion](https://github.com/evsio0n/minizep/blob/main/src/pipeline/ingest.ts): `src/pipeline/ingest.ts`
- [Hybrid retrieval](https://github.com/evsio0n/minizep/blob/main/src/search/retrieval.ts): `src/search/retrieval.ts`
- [Graph reranking](https://github.com/evsio0n/minizep/blob/main/src/search/rerank.ts): `src/search/rerank.ts`
- [Temporal model](https://github.com/evsio0n/minizep/blob/main/src/model/types.ts): `src/model/types.ts`

### Memory storage

- [Graph store API](https://github.com/evsio0n/minizep/blob/main/src/store/memory-store.ts): `src/store/memory-store.ts`
- [Memory graph](https://github.com/evsio0n/minizep/blob/main/src/store/memory-store.ts): `src/store/memory-store.ts`
- [Postgres graph](https://github.com/evsio0n/minizep/blob/main/src/store/postgres-store.ts): `src/store/postgres-store.ts`
- [Snapshot persistence](https://github.com/evsio0n/minizep/blob/main/src/store/persistence.ts): `src/store/persistence.ts`

### Model providers

- [Provider interfaces](https://github.com/evsio0n/minizep/blob/main/src/provider/interfaces.ts): `src/provider/interfaces.ts`
- [LLM providers](https://github.com/evsio0n/minizep/blob/main/src/provider/openai-llm.ts): `src/provider/openai-llm.ts`
- [Embedding providers](https://github.com/evsio0n/minizep/blob/main/src/provider/openai-embedder.ts): `src/provider/openai-embedder.ts`

### Other components

- **AI agent**
- **LLM service**
- **Embedding service**

## Connections

- AI agent → MCP server: sends MCP
- AI agent → HTTP application: sends HTTP
- AI agent → stdio HTTP bridge: uses stdio
- stdio HTTP bridge → HTTP application: forwards requests
- MCP server → stdio transport: uses transport
- MCP server → MCP tools: dispatches tools
- HTTP application → REST API: dispatches REST
- HTTP application → MCP server: dispatches MCP
- HTTP application → Web UI: serves UI
- HTTP application → Memory service: routes requests
- HTTP application → Authentication: checks identity
- MCP tools → Memory service: invokes operations
- REST API → Memory service: invokes operations
- Web UI → REST API: calls UI API
- Memory service → Authentication: resolves groups
- Memory service → Access control: manages access
- Memory service → Minizep API: calls memory API
- Memory service → Ingestion jobs: queues ingestion
- Memory service → Snapshot persistence: persists snapshots
- Minizep API → Episode ingestion: ingests episodes
- Minizep API → Hybrid retrieval: retrieves facts
- Hybrid retrieval → Graph reranking: reranks candidates
- Minizep API → Graph store API: reads and writes
- Episode ingestion → Graph store API: writes graph
- Episode ingestion → LLM providers: extracts facts
- Episode ingestion → Embedding providers: embeds records
- Hybrid retrieval → Graph store API: reads graph
- Hybrid retrieval → Embedding providers: embeds query
- Graph store API → Memory graph: uses memory backend
- Graph store API → Postgres graph: uses database backend
- Snapshot persistence → Memory graph: snapshots graph
- Memory graph → Temporal model: stores temporal records
- Postgres graph → Temporal model: stores temporal records
- LLM providers → Provider interfaces: implements provider
- Embedding providers → Provider interfaces: implements provider
- LLM providers → LLM service: calls completion API
- Embedding providers → Embedding service: requests vectors