# deepagents-ai/agent-backend architecture

> Architecture diagram of the GitHub repository deepagents-ai/agent-backend, 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/deepagents-ai/agent-backend
- Repository: https://github.com/deepagents-ai/agent-backend

## Overview

Agent Backend provides filesystem and memory access to agents through client libraries and sandbox daemons; Agent Document Room builds a search-to-workspace-to-commit workflow on top. Its documented capabilities include MCP and SSH access, scoped backends, multiple workspace runtimes, semantic text/image search, and durable versioned storage. The graph combines these products with the indexing and storage packages. Several implementation paths are unsampled, so links for those branches rely only on README or source-index evidence.

Main entry points: [`packages/agent-backend/typescript/src/backends/index.ts`](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/index.ts) (Backend Clients), [`room/src/room-service.ts`](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/room-service.ts) (Room Service), [`room/src/manifest-room-catalog.ts`](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/manifest-room-catalog.ts) (Room Catalog), [`room/src/mcp/server.ts`](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/mcp/server.ts) (Room MCP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Agent Backend"]
  node_client["Backend Clients<br/>[index.ts]"]
  node_local["Local Backend"]
  node_memory[("Memory Backend<br/>[MemoryBackend.ts]")]
  node_remote["Remote Backend"]
  node_scoped["Scoped Backends"]
  node_pool["Backend Pool"]
  node_daemon["MCP and SSH"]
end

subgraph group_room["Document Room"]
  node_roommcp["Room MCP API<br/>[server.ts]"]
  node_service["Room Service<br/>[room-service.ts]"]
  node_sessions["Warm Sessions"]
  node_catalog["Room Catalog"]
  node_workspaces["Workspace Providers"]
  node_workingtree["Working Tree Adapter"]
end

subgraph group_search["Search and Ingestion"]
  node_ingestion["PDF Ingestion<br/>[pdf.ts]"]
  node_indexsync["Index Synchronization<br/>[index-sync.ts]"]
  node_imageindex["Image Indexing"]
  node_embeddings["Embedding Providers<br/>[factory.ts]"]
  node_vectorstore["Vector Store Adapter<br/>[vector-store.ts]"]
  node_pg[("Postgres Vectors<br/>[index.ts]")]
end

subgraph group_storage["Versioned Storage"]
  node_versionstore["Versioned Store<br/>[versioned-store.ts]"]
  node_manifest["Manifest and Hashing<br/>[manifest.ts]"]
  node_s3[("S3 Storage<br/>[s3.ts]")]
end

node_agent(("AI Agent"))

node_agent -->|"uses"| node_client
node_client -->|"selects"| node_local
node_client -->|"selects"| node_remote
node_client -->|"selects"| node_memory
node_client -->|"selects"| node_scoped
node_pool -->|"manages"| node_client
node_agent -->|"accesses"| node_daemon
node_agent -->|"uses"| node_roommcp
node_roommcp -->|"invokes"| node_service
node_roommcp -->|"manages"| node_sessions
node_service -->|"queries"| node_catalog
node_service -.->|"provisions"| node_workspaces
node_service -->|"adapts"| node_workingtree
node_catalog -->|"indexes and searches"| node_indexsync
node_catalog -->|"reads and commits"| node_versionstore
node_ingestion -.->|"supplies documents"| node_catalog
node_indexsync -.->|"embeds"| node_embeddings
node_indexsync -->|"uses"| node_vectorstore
node_imageindex -.->|"embeds images"| node_embeddings
node_pg -->|"implements"| node_vectorstore
node_versionstore -->|"hashes and merges"| node_manifest
node_versionstore -.->|"persists blobs and manifests"| node_s3

click node_client "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/index.ts"
click node_local "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/LocalFilesystemBackend.ts"
click node_memory "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/MemoryBackend.ts"
click node_remote "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/RemoteFilesystemBackend.ts"
click node_scoped "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/ScopedFilesystemBackend.ts"
click node_pool "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/BackendPoolManager.ts"
click node_daemon "https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/server/AgentBackendMCPServer.ts"
click node_roommcp "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/mcp/server.ts"
click node_service "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/room-service.ts"
click node_sessions "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/session-registry.ts"
click node_catalog "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/manifest-room-catalog.ts"
click node_workspaces "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/workspace-docker.ts"
click node_workingtree "https://github.com/deepagents-ai/agent-backend/blob/main/room/src/lib/backend-working-tree.ts"
click node_ingestion "https://github.com/deepagents-ai/agent-backend/blob/main/packages/ingestion/src/pdf.ts"
click node_indexsync "https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/index-sync.ts"
click node_imageindex "https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/image-index-sync.ts"
click node_embeddings "https://github.com/deepagents-ai/agent-backend/blob/main/packages/embeddings/src/factory.ts"
click node_vectorstore "https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/vector-store.ts"
click node_versionstore "https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/versioned-store.ts"
click node_manifest "https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/manifest.ts"
click node_s3 "https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/stores/s3.ts"
click node_pg "https://github.com/deepagents-ai/agent-backend/blob/main/packages/vector-pg/src/index.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_client,node_local,node_memory,node_remote,node_scoped,node_pool,node_daemon toneBlue
class node_roommcp,node_service,node_sessions,node_catalog,node_workspaces,node_workingtree toneAmber
class node_ingestion,node_indexsync,node_imageindex,node_embeddings,node_vectorstore,node_pg toneMint
class node_versionstore,node_manifest,node_s3 toneRose
class node_agent toneIndigo
```

## Components

### Agent Backend

- [Backend Clients](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/index.ts): `packages/agent-backend/typescript/src/backends/index.ts`
- [Local Backend](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/LocalFilesystemBackend.ts): `packages/agent-backend/typescript/src/backends/LocalFilesystemBackend.ts`
- [Memory Backend](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/MemoryBackend.ts): `packages/agent-backend/typescript/src/backends/MemoryBackend.ts`
- [Remote Backend](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/RemoteFilesystemBackend.ts): `packages/agent-backend/typescript/src/backends/RemoteFilesystemBackend.ts`
- [Scoped Backends](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/backends/ScopedFilesystemBackend.ts): `packages/agent-backend/typescript/src/backends/ScopedFilesystemBackend.ts`
- [Backend Pool](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/BackendPoolManager.ts): `packages/agent-backend/typescript/src/BackendPoolManager.ts`
- [MCP and SSH](https://github.com/deepagents-ai/agent-backend/blob/main/packages/agent-backend/typescript/src/server/AgentBackendMCPServer.ts): `packages/agent-backend/typescript/src/server/AgentBackendMCPServer.ts`

### Document Room

- [Room MCP API](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/mcp/server.ts): `room/src/mcp/server.ts`
- [Room Service](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/room-service.ts): `room/src/room-service.ts`
- [Warm Sessions](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/session-registry.ts): `room/src/session-registry.ts`
- [Room Catalog](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/manifest-room-catalog.ts): `room/src/manifest-room-catalog.ts`
- [Workspace Providers](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/workspace-docker.ts): `room/src/workspace-docker.ts`
- [Working Tree Adapter](https://github.com/deepagents-ai/agent-backend/blob/main/room/src/lib/backend-working-tree.ts): `room/src/lib/backend-working-tree.ts`

### Search and Ingestion

- [PDF Ingestion](https://github.com/deepagents-ai/agent-backend/blob/main/packages/ingestion/src/pdf.ts): `packages/ingestion/src/pdf.ts`
- [Index Synchronization](https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/index-sync.ts): `packages/index-sync/src/index-sync.ts`
- [Image Indexing](https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/image-index-sync.ts): `packages/index-sync/src/image-index-sync.ts`
- [Embedding Providers](https://github.com/deepagents-ai/agent-backend/blob/main/packages/embeddings/src/factory.ts): `packages/embeddings/src/factory.ts`
- [Vector Store Adapter](https://github.com/deepagents-ai/agent-backend/blob/main/packages/index-sync/src/vector-store.ts): `packages/index-sync/src/vector-store.ts`
- [Postgres Vectors](https://github.com/deepagents-ai/agent-backend/blob/main/packages/vector-pg/src/index.ts): `packages/vector-pg/src/index.ts`

### Versioned Storage

- [Versioned Store](https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/versioned-store.ts): `packages/versioned-store/src/versioned-store.ts`
- [Manifest and Hashing](https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/manifest.ts): `packages/versioned-store/src/manifest.ts`
- [S3 Storage](https://github.com/deepagents-ai/agent-backend/blob/main/packages/versioned-store/src/stores/s3.ts): `packages/versioned-store/src/stores/s3.ts`

### Other components

- **AI Agent**

## Connections

- AI Agent → Backend Clients: uses
- Backend Clients → Local Backend: selects (evidence: `packages/agent-backend/typescript/src/backends/index.ts`)
- Backend Clients → Remote Backend: selects (evidence: `packages/agent-backend/typescript/src/backends/index.ts`)
- Backend Clients → Memory Backend: selects (evidence: `packages/agent-backend/typescript/src/backends/index.ts`)
- Backend Clients → Scoped Backends: selects (evidence: `packages/agent-backend/typescript/src/backends/index.ts`)
- Backend Pool → Backend Clients: manages (evidence: `packages/agent-backend/typescript/src/BackendPoolManager.ts`)
- AI Agent → MCP and SSH: accesses
- AI Agent → Room MCP API: uses
- Room MCP API → Room Service: invokes (evidence: `room/src/mcp/server.ts`)
- Room MCP API → Warm Sessions: manages (evidence: `room/src/mcp/server.ts`)
- Room Service → Room Catalog: queries (evidence: `room/src/room-service.ts`)
- Room Service → Workspace Providers: provisions
- Room Service → Working Tree Adapter: adapts (evidence: `room/src/room-service.ts`)
- Room Catalog → Index Synchronization: indexes and searches (evidence: `room/src/manifest-room-catalog.ts`)
- Room Catalog → Versioned Store: reads and commits (evidence: `room/src/manifest-room-catalog.ts`)
- PDF Ingestion → Room Catalog: supplies documents
- Index Synchronization → Embedding Providers: embeds
- Index Synchronization → Vector Store Adapter: uses (evidence: `packages/index-sync/src/index-sync.ts`)
- Image Indexing → Embedding Providers: embeds images
- Postgres Vectors → Vector Store Adapter: implements (evidence: `packages/vector-pg/src/index.ts`)
- Versioned Store → Manifest and Hashing: hashes and merges (evidence: `packages/versioned-store/src/versioned-store.ts`)
- Versioned Store → S3 Storage: persists blobs and manifests
