# krshirkoohi/tana-context-mask architecture

> Architecture diagram of the GitHub repository krshirkoohi/tana-context-mask, 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/krshirkoohi/tana-context-mask
- Repository: https://github.com/krshirkoohi/tana-context-mask

## Overview

Tana Semantic Engine mirrors a Tana workspace and turns natural-language tasks into grounded context packets for AI clients. The main workflow is context acquisition: hybrid semantic/lexical and temporal retrieval finds seed notes, graph expansion adds structural evidence, reranking selects useful nodes, and the system returns formatted context with citations and provenance. Search, node inspection, synchronization, and MCP access are also product capabilities. The repository contains self-hosted Python and Cloudflare Worker implementations; sampled excerpts do not expose all orchestration details, so uncertain internal links are omitted.

Main entry points: [`worker/src/index.ts`](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/index.ts) (Worker Gateway), [`tana_context_mask/engine/context_builder.py`](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/context_builder.py) (Context Builder), [`tana_context_mask/engine/semantic_search.py`](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/semantic_search.py) (Semantic Search), [`tana_context_mask/api/server.py`](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/api/server.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client Interfaces"]
  node_python_api["REST API<br/>[server.py]"]
  node_python_mcp["MCP Server<br/>[mcp_server.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_acquisition["Context Acquisition"]
  node_context["Context Builder<br/>[context_builder.py]"]
  node_packet["Context Packet<br/>[context.py]"]
end

subgraph group_retrieval["Retrieval And Graph"]
  node_search["Semantic Search<br/>[semantic_search.py]"]
  node_graph["Graph Expansion<br/>[graph_engine.py]"]
  node_reranker["Reranker<br/>[reranker.py]"]
  node_temporal["Temporal Routing<br/>[temporal.py]"]
end

subgraph group_mirror["Workspace Mirror"]
  node_db[("SQLite Mirror<br/>[db.py]")]
  node_vectors[("Vector Store<br/>[vector_store.py]")]
  node_sync["Mirror Sync<br/>[mirror_engine.py]"]
  node_tana_client["Tana MCP Client<br/>[tana_mcp_client.py]"]
end

subgraph group_edge["Cloudflare Runtime"]
  node_edge_api["Worker Gateway<br/>[index.ts]"]
  node_edge_search["Hybrid Search<br/>[search.ts]"]
  node_edge_graph["D1 Graph Store<br/>[graph.ts]"]
  node_edge_rank["Edge Reranker<br/>[reranker.ts]"]
  node_edge_sync["Edge Sync<br/>[sync.ts]"]
  node_edge_mcp["Remote MCP<br/>[mcp.ts]"]
end

node_ai(("AI Client"))
node_tana[("Tana Workspace")]
node_cloudflare_db[("Cloudflare D1")]
node_vectorize[("Vectorize")]
node_workers_ai["Workers AI"]

node_ai -->|"requests context"| node_python_api
node_ai -->|"uses MCP"| node_python_mcp
node_ai -->|"calls gateway"| node_edge_api
node_cli -->|"acquires context"| node_context
node_cli -->|"searches"| node_search
node_cli -->|"starts sync"| node_sync
node_python_api -->|"acquires context"| node_context
node_python_api -->|"searches"| node_search
node_python_api -->|"inspects nodes"| node_graph
node_python_api -->|"starts sync"| node_sync
node_context -->|"retrieves seeds"| node_search
node_context -->|"expands graph"| node_graph
node_context -->|"ranks candidates"| node_reranker
node_context -->|"formats result"| node_packet
node_search -->|"reads candidates"| node_db
node_search -->|"queries vectors"| node_vectors
node_search -->|"scores dates"| node_temporal
node_graph -->|"reads relations"| node_db
node_sync -->|"requests workspace data"| node_tana_client
node_sync -->|"writes mirror"| node_db
node_sync -->|"updates embeddings"| node_vectors
node_tana_client -->|"calls Remote MCP"| node_tana
node_edge_api -->|"dispatches MCP"| node_edge_mcp
node_edge_api -->|"runs retrieval"| node_edge_search
node_edge_api -->|"expands context"| node_edge_graph
node_edge_api -->|"reranks candidates"| node_edge_rank
node_edge_api -->|"dispatches sync"| node_edge_sync
node_edge_search -->|"loads nodes"| node_edge_graph
node_edge_search -->|"queries lexical index"| node_cloudflare_db
node_edge_search -->|"searches vectors"| node_vectorize
node_edge_search -->|"embeds query"| node_workers_ai
node_edge_graph -->|"reads graph"| node_cloudflare_db
node_edge_mcp -->|"calls Remote MCP"| node_tana
node_edge_sync -->|"syncs workspace"| node_tana
node_edge_sync -->|"updates mirror"| node_cloudflare_db
node_edge_sync -->|"updates vectors"| node_vectorize

click node_python_api "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/api/server.py"
click node_python_mcp "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/api/mcp_server.py"
click node_cli "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/cli/main.py"
click node_context "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/context_builder.py"
click node_packet "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/models/context.py"
click node_search "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/semantic_search.py"
click node_graph "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/graph_engine.py"
click node_reranker "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/reranker.py"
click node_temporal "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/temporal.py"
click node_db "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/storage/db.py"
click node_vectors "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/storage/vector_store.py"
click node_sync "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/sync/mirror_engine.py"
click node_tana_client "https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/client/tana_mcp_client.py"
click node_edge_api "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/index.ts"
click node_edge_search "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/search.ts"
click node_edge_graph "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/graph.ts"
click node_edge_rank "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/reranker.ts"
click node_edge_sync "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/sync.ts"
click node_edge_mcp "https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/mcp.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_python_api,node_python_mcp,node_cli,node_ai toneBlue
class node_context,node_packet,node_tana,node_cloudflare_db,node_vectorize toneAmber
class node_search,node_graph,node_reranker,node_temporal toneMint
class node_db,node_vectors,node_sync,node_tana_client,node_workers_ai toneRose
class node_edge_api,node_edge_search,node_edge_graph,node_edge_rank,node_edge_sync,node_edge_mcp toneIndigo
```

## Components

### Client Interfaces

- [REST API](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/api/server.py): `tana_context_mask/api/server.py`
- [MCP Server](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/api/mcp_server.py): `tana_context_mask/api/mcp_server.py`
- [CLI](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/cli/main.py): `tana_context_mask/cli/main.py`

### Context Acquisition

- [Context Builder](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/context_builder.py): `tana_context_mask/engine/context_builder.py`
- [Context Packet](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/models/context.py): `tana_context_mask/models/context.py`

### Retrieval And Graph

- [Semantic Search](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/semantic_search.py): `tana_context_mask/engine/semantic_search.py`
- [Graph Expansion](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/graph_engine.py): `tana_context_mask/engine/graph_engine.py`
- [Reranker](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/reranker.py): `tana_context_mask/engine/reranker.py`
- [Temporal Routing](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/engine/temporal.py): `tana_context_mask/engine/temporal.py`

### Workspace Mirror

- [SQLite Mirror](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/storage/db.py): `tana_context_mask/storage/db.py`
- [Vector Store](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/storage/vector_store.py): `tana_context_mask/storage/vector_store.py`
- [Mirror Sync](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/sync/mirror_engine.py): `tana_context_mask/sync/mirror_engine.py`
- [Tana MCP Client](https://github.com/krshirkoohi/tana-context-mask/blob/main/tana_context_mask/client/tana_mcp_client.py): `tana_context_mask/client/tana_mcp_client.py`

### Cloudflare Runtime

- [Worker Gateway](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/index.ts): `worker/src/index.ts`
- [Hybrid Search](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/search.ts): `worker/src/services/search.ts`
- [D1 Graph Store](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/graph.ts): `worker/src/services/graph.ts`
- [Edge Reranker](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/reranker.ts): `worker/src/services/reranker.ts`
- [Edge Sync](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/sync.ts): `worker/src/services/sync.ts`
- [Remote MCP](https://github.com/krshirkoohi/tana-context-mask/blob/main/worker/src/services/mcp.ts): `worker/src/services/mcp.ts`

### Other components

- **AI Client**
- **Tana Workspace**
- **Cloudflare D1**
- **Vectorize**
- **Workers AI**

## Connections

- AI Client → REST API: requests context
- AI Client → MCP Server: uses MCP
- AI Client → Worker Gateway: calls gateway
- CLI → Context Builder: acquires context
- CLI → Semantic Search: searches
- CLI → Mirror Sync: starts sync
- REST API → Context Builder: acquires context
- REST API → Semantic Search: searches
- REST API → Graph Expansion: inspects nodes
- REST API → Mirror Sync: starts sync
- Context Builder → Semantic Search: retrieves seeds
- Context Builder → Graph Expansion: expands graph
- Context Builder → Reranker: ranks candidates
- Context Builder → Context Packet: formats result
- Semantic Search → SQLite Mirror: reads candidates
- Semantic Search → Vector Store: queries vectors
- Semantic Search → Temporal Routing: scores dates
- Graph Expansion → SQLite Mirror: reads relations
- Mirror Sync → Tana MCP Client: requests workspace data
- Mirror Sync → SQLite Mirror: writes mirror
- Mirror Sync → Vector Store: updates embeddings
- Tana MCP Client → Tana Workspace: calls Remote MCP
- Worker Gateway → Remote MCP: dispatches MCP
- Worker Gateway → Hybrid Search: runs retrieval
- Worker Gateway → D1 Graph Store: expands context
- Worker Gateway → Edge Reranker: reranks candidates
- Worker Gateway → Edge Sync: dispatches sync
- Hybrid Search → D1 Graph Store: loads nodes
- Hybrid Search → Cloudflare D1: queries lexical index
- Hybrid Search → Vectorize: searches vectors
- Hybrid Search → Workers AI: embeds query
- D1 Graph Store → Cloudflare D1: reads graph
- Remote MCP → Tana Workspace: calls Remote MCP
- Edge Sync → Tana Workspace: syncs workspace
- Edge Sync → Cloudflare D1: updates mirror
- Edge Sync → Vectorize: updates vectors